PHPackages                             superinstance/flux-vm - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. superinstance/flux-vm

ActiveLibrary[Utility & Helpers](/categories/utility)

superinstance/flux-vm
=====================

Pure PHP FLUX ISA v3.0 virtual machine — register-based bytecode VM for multi-agent fleet coordination

1.0.0(1mo ago)10MITPHPPHP >=8.0CI failing

Since May 3Pushed 1mo agoCompare

[ Source](https://github.com/SuperInstance/flux-vm-php)[ Packagist](https://packagist.org/packages/superinstance/flux-vm)[ Docs](https://github.com/SuperInstance/flux-vm-php)[ RSS](/packages/superinstance-flux-vm/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

FLUX ISA v3.0 Virtual Machine
=============================

[](#flux-isa-v30-virtual-machine)

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
------------

[](#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
---------------------

[](#architecture-overview)

### Register Model

[](#register-model)

FLUX provides three separate register files plus system registers:

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

RegisterAliasPurposeR0–R7—General-purpose, caller-savedR8RVReturn valueR9A0First function argumentR10A1Second function argumentR11SPStack pointer (descends)R12FPFrame pointerR13FLFlags registerR14TPTemporary / reservedR15LRLink register (CALL stores return address)**Floating Point Registers (FPR)** — 16 registers, 32-bit IEEE 754:

RegisterAliasPurposeF0–F7—General-purpose, caller-savedF8FVReturn value (float)F9FA0First float argumentF10FA1Second float argumentF11–F15—General-purpose**Vector Registers** — 16 registers, 256 bytes each (SIMD-style).

### Memory Model

[](#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)

[](#flags-register-fl--r13)

BitNameDescriptionZZeroResult is zeroSSignResult is negativeCCarryUnsigned overflowVOverflowSigned overflowInstruction Formats
-------------------

[](#instruction-formats)

### Format A — Nullary (1 byte)

[](#format-a--nullary-1-byte)

```
[ opcode (1 byte) ]

```

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

### Format B — Two Registers (3 bytes)

[](#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)

[](#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)

[](#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)

[](#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)

[](#format-g--variable-length-2n-bytes)

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

```

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

Opcode Coverage Table
---------------------

[](#opcode-coverage-table)

### Control Flow (0x00–0x0F)

[](#control-flow-0x000x0f)

HexNameFormatDescription0x00HaltAStop execution0x01NopANo operation0x02RetAReturn from function0x03JumpGUnconditional branch0x04JumpIfGBranch if register != 00x05JumpIfNotGBranch if register == 00x06CallGCall function by index0x07CallIndirectGCall function by address0x08YieldAPause execution0x09PanicAAbort with error0x0AUnreachableATrap (should not execute)### Stack Operations (0x10–0x1F)

[](#stack-operations-0x100x1f)

HexNameFormatDescription0x10PushBPush GP\[Rs\] to stack0x11PopBPop stack to GP\[Rd\]0x12DupBCopy register0x13SwapBSwap two registers### Integer Arithmetic (0x20–0x3F)

[](#integer-arithmetic-0x200x3f)

HexNameFormatDescription0x20IMovBCopy GP register0x21IAddCRd = Ra + Rb0x22ISubCRd = Ra - Rb0x23IMulCRd = Ra \* Rb0x24IDivCRd = Ra / Rb0x25IModCRd = Ra % Rb0x26INegCRd = -Ra0x27IAbsCRd = abs(Ra)0x28IIncDRd += immediate0x29IDecDRd -= immediate0x2AIMinCRd = min(Ra, Rb)0x2BIMaxCRd = max(Ra, Rb)0x2CIAndCRd = Ra & Rb0x2DIOrCRd = Ra | Rb0x2EIXorCRd = Ra ^ Rb0x2FIShlCRd = Ra << Rb0x30IShrCRd = Ra >> Rb0x31INotCRd = ~Ra0x32ICmpEqCRd = (Ra == Rb)0x33ICmpNeCRd = (Ra != Rb)0x34ICmpLtCRd = (Ra < Rb)0x35ICmpLeCRd = (Ra <= Rb)0x36ICmpGtCRd = (Ra > Rb)0x37ICmpGeCRd = (Ra >= Rb)### Float Arithmetic (0x40–0x5F)

[](#float-arithmetic-0x400x5f)

HexNameFormatDescription0x40FMovBCopy FP register0x41FAddCRd = Ra + Rb0x42FSubCRd = Ra - Rb0x43FMulCRd = Ra \* Rb0x44FDivCRd = Ra / Rb0x45FModCRd = fmod(Ra, Rb)0x46FNegCRd = -Ra0x47FAbsCRd = abs(Ra)0x48FSqrtCRd = sqrt(Ra)0x49FFloorCRd = floor(Ra)0x4AFCeilCRd = ceil(Ra)0x4BFRoundCRd = round(Ra)0x4CFMinCRd = min(Ra, Rb)0x4DFMaxCRd = max(Ra, Rb)0x4EFSinCRd = sin(Ra)0x4FFCosCRd = cos(Ra)0x50FExpCRd = exp(Ra)0x51FLogCRd = log(Ra)0x52FClampCRd = clamp(Ra, Rb)0x53FLerpCRd = lerp(Ra, Rb)0x54FCmpEqCRd = (Ra == Rb)0x55FCmpNeCRd = (Ra != Rb)0x56FCmpLtCRd = (Ra < Rb)0x57FCmpLeCRd = (Ra <= Rb)0x58FCmpGtCRd = (Ra > Rb)0x59FCmpGeCRd = (Ra >= Rb)### Conversions (0x60–0x6F)

[](#conversions-0x600x6f)

HexNameFormatDescription0x60IToFCFP\[Rd\] = (float)GP\[Ra\]0x61FToICGP\[Rd\] = (int)FP\[Ra\]0x62BToICGP\[Rd\] = (Ra != 0)0x63IToBCGP\[Rd\] = (Ra != 0)### Memory Operations (0x70–0x7F)

[](#memory-operations-0x700x7f)

HexNameFormatDescription0x70Load8EGP\[Rd\] = mem\[Rb+off\] (u8)0x71Load16EGP\[Rd\] = mem\[Rb+off\] (u16)0x72Load32EGP\[Rd\] = mem\[Rb+off\] (u32)0x73Load64EGP\[Rd\] = mem\[Rb+off\] (u64)0x74Store8Emem\[Rb+off\] = GP\[Rs\]0x75Store16Emem\[Rb+off\] = GP\[Rs\]0x76Store32Emem\[Rb+off\] = GP\[Rs\]0x77Store64Emem\[Rb+off\] = GP\[Rs\]0x78LoadAddrEGP\[Rd\] = Rb + off0x79StackAllocDAllocate stack frame### Agent-to-Agent Communication (0x80–0x8F)

[](#agent-to-agent-communication-0x800x8f)

HexNameFormatDescription0x80ASendGSend message (non-blocking)0x81ARecvGReceive message (blocking)0x82AAskGSend request, wait response0x83ATellGFire-and-forget message0x84ADelegateGDelegate bytecode execution0x85ABroadcastGBroadcast to all agents0x86ASubscribeGSubscribe to channel0x87AWaitGBlock until condition0x88ATrustGEstablish trust0x89AVerifyGVerify trust level### Type/Meta Operations (0x90–0x9F)

[](#typemeta-operations-0x900x9f)

HexNameFormatDescription0x90CastCType-cast value0x91SizeOfCSize of type0x92TypeOfCRuntime type tag### Bitwise Operations (0xA0–0xAF)

[](#bitwise-operations-0xa00xaf)

HexNameFormatDescription0xA0BAndCRd = Ra & Rb0xA1BOrCRd = Ra | Rb0xA2BXorCRd = Ra ^ Rb0xA3BShlCRd = Ra << Rb0xA4BShrCRd = Ra >> Rb0xA5BNotCRd = ~Ra### Vector/SIMD Operations (0xB0–0xBF)

[](#vectorsimd-operations-0xb00xbf)

HexNameFormatDescription0xB0VLoadELoad vector from memory0xB1VStoreEStore vector to memory0xB2VAddCComponent-wise addition0xB3VMulCComponent-wise multiply0xB4VDotCDot product (scalar result)Usage Examples
--------------

[](#usage-examples)

### CLI

[](#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

[](#programmatic-usage)

```