⚡ FLUX — Rust Bytecode VM

FLUX — Fluid Language Universal eXecution A register-based bytecode VM for deterministic agent computation. Published on crates.io as fluxvm.

Quick Start

cargo add fluxvm

use flux_core::bytecode::assembler::Assembler;
use flux_core::vm::Interpreter;

let bytecode = Assembler::assemble("MOVI R0, 42\nHALT").unwrap();
let mut vm = Interpreter::new(&bytecode);
vm.execute().unwrap();
assert_eq!(vm.read_gp(0), 42);

Natural language → bytecode:

use flux_core::vocabulary::Interpreter;

let interp = Interpreter::with_builtins();
assert_eq!(interp.execute("compute 6 * 7").unwrap(), 42);
assert_eq!(interp.execute("factorial of 5").unwrap(), 120);

What It Does

FLUX is the bytecode VM that runs inside the shell. Not the shell itself — the mechanism. It executes deterministic programs so agents don't need to agree on what "add R1, R2" means. When an agent needs to compute something, it doesn't reach for Python or Bash — it reaches for FLUX. A compact, auditable, register-based VM that does exactly one thing: execute bytecode predictably, every time, on every agent.

Most agent frameworks interpret high-level language directly. FLUX takes a different route: it compiles natural-language intents into bytecode, executes them on a deterministic VM, and lets agents share results through a structured A2A protocol. This matters because:

• Determinism — Same bytecode, same result. Every node can verify.
• Auditability — Disassemble any agent's program. See exactly what it would do.
• Sandboxing — Cycle budgets prevent runaway execution.
• Swarm coordination — Built-in majority voting and message passing.

Architecture

FLUX embodies γ + η = C: the fixed, deterministic bytecode contract (γ) plus the adaptive vocabulary and coordination layer (η) equals the complete agent execution system (C).

Register File

RegisterFile {
    gp: [i32; 16],   // general purpose registers (R0–R15)
    fp: [f64; 16],   // floating point registers
    pc: u32,         // program counter
    sp: u32,         // stack pointer
    flag_zero: bool, // set by CMP
    flag_sign: bool, // set by CMP
}

16 general-purpose registers, 16 floating-point registers, a program counter, stack pointer, and two condition flags. Simple. Familiar. Predictable.

Instruction Set (0x00–0x81)

Single-byte opcodes. 1–4 byte instructions. O(1) per instruction fetch-decode-execute.

A2A Protocol

Messages carry: | sender 16B | receiver 16B | conv_id 16B | type 1B | len 2B | payload | trust 4B |. UUID-paired agents with floating-point trust scores [0, 1].

Swarm Consensus

Run N agents for one tick each. Majority vote on a register value — O(N) per tick, verifiable, shell-agnostic.

FLUX is the Rust implementation in the SuperInstance ecosystem — the fastest FLUX VM, used where determinism and performance matter most. Same bytecode ISA runs across Python, JavaScript, C, Zig, Go, and more.

API / Usage

Module Overview

Assembly Syntax

loop:
    CMP R1, 0       ; compare R1 to zero
    JZ end           ; jump if zero
    IMUL R0, R1     ; R0 *= R1
    DEC R1           ; R1 -= 1
    JMP loop         ; back to top
end:
    HALT

Testing

cargo test
# 51 tests covering: VM execution, assembler, disassembler,
# vocabulary patterns, A2A messaging, swarm consensus

Contributing

Contributions are welcome! See the SuperInstance Contributing Guide.

1. Fork the repo
2. Create a feature branch
3. Add tests for new functionality
4. Ensure cargo test passes
5. Submit a PR

📦 Related Packages

Additional implementations: C · Zig · Go · Java · WASM · CUDA

Ecosystem

This repo is part of the SuperInstance flagship ecosystem — agent-first computation, constraint theory, and self-improving runtimes.

FLUX Runtime Family

PLATO Engine Family

Constraint / Theory Family

Agent / Infrastructure Family

Registries

Philosophy & Architecture

• 📖 AI-Writings — Philosophy, essays, and design rationale
• 📦 PACKAGES.md — Full package index

License

MIT

The crab inherits the shell. 🦀