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

Category	Opcodes	Description
Arithmetic	0x08–0x0F	IADD, ISUB, IMUL, IDIV, IMOD, INEG, INC, DEC
Logic	0x10–0x15	IAND, IOR, IXOR, INOT, ISHL, ISHR
Control Flow	0x04–0x07	JMP, JZ, JNZ, CALL
Stack	0x20–0x22, 0x28	PUSH, POP, DUP, RET
Memory	0x01, 0x2B	MOV, MOVI (immediate)
Comparison	0x2D	CMP (sets zero/sign flags)
A2A	0x60–0x66	TELL, ASK, DELEGATE, BROADCAST
System	0x80, 0x81	HALT, YIELD

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

Module	Key Types	Purpose
vm	Interpreter, RegisterFile	Bytecode execution
bytecode	Op, Assembler, Disassembler	Encode/decode instructions
vocabulary	VocabEntry, Vocabulary, Interpreter	NL pattern → assembly
a2a	A2AMessage, Agent, Swarm	Agent protocol
error	FluxError	All error variants

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

Package	Language	Registry	Install
flux-vm	Python	PyPI	pip install flux-vm
fluxvm	Rust	crates.io	cargo add fluxvm
flux-js	JavaScript	npm	npm install flux-js

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

Repo	Language	Description
flux-runtime	Python	Full FLUX runtime: markdown→bytecode, 2037 tests, zero deps
flux-core	Rust	Register-based bytecode VM, deterministic agent computation
flux-js	JavaScript	FLUX VM for Node.js and browsers, ~400ns/iter
flux-compiler	Rust/Python	Formal-methods compiler for safety-critical codegen
flux-vm	Rust	Stack-based constraint-checking VM, 50 opcodes, Turing-incomplete

PLATO Engine Family

Repo	Language	Description
plato-server	Python	Knowledge tiles, fleet sync via Matrix, HTTP API
plato-engine-block	Rust	Original room runtime: no_std + alloc, builder pattern
plato-engine-block-c	C99	Embedded reference: zero heap alloc, bare-metal portable
plato-engine-block-elixir	Elixir	BEAM supervision trees, fault tolerance, hot reload
plato-runtime-kernel	Rust	Spatial model: tensor grid, batons, assertion traps

Constraint / Theory Family

Repo	Language	Description
categorical-agents	Rust	Category theory for agent composition (functors, naturality)
cuda-constraint-engine	CUDA/C	GPU constraint checking at 1B+ constraints/sec
grand-pattern-rs	Rust	Fibonacci dual-direction cellular graph architecture
lau-hodge-theory	Rust	Hodge decomposition, Betti numbers, spectral sequences
ternary-science	Rust	Experimental evidence for ternary intelligence, 5 conservation laws

Agent / Infrastructure Family

Repo	Language	Description
construct-core	Rust	Layered trait system: bare-metal → alloc → async agent runtime
crab	Bash	Agent shell for repo entry/leave (MUD-room metaphor)
exocortex	Rust	Persistent cognitive substrate, S3-compatible memory
git-agent	Python	The repo IS the agent — autonomous lifecycle via Git
capitaine-1	TypeScript	Git-native repo-agent, Cloudflare Workers heartbeat
codespace-edge-rd	Research	Codespace→Edge agent lifecycle and yoke transfer protocols
git-agent-codespace	DevContainer	One-click Codespace template for Git-Agent runtimes

Registries

Registry	Package	Install
PyPI	flux-vm	pip install flux-vm
crates.io	fluxvm	cargo add fluxvm
npm	flux-js	npm install flux-js

Philosophy & Architecture

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

---

License

MIT

---

The crab inherits the shell. 🦀