FLUX.js — JavaScript Bytecode VM

FLUX — Fluid Language Universal eXecution Self-contained FLUX runtime for Node.js and browsers. ~400ns/iter via V8 JIT.

Quick Start

npm install flux-js

const { FluxVM, assemble } = require('flux-js');

const bc = assemble('MOVI R0, 42\nHALT');
const vm = new FluxVM(bc);
vm.execute();
console.log(vm.reg(0)); // 42

What It Does

FLUX.js brings the FLUX bytecode virtual machine to JavaScript runtimes — Node.js and browsers. It implements the same register-based ISA, opcode set, and A2A agent messaging protocol as the Python and Rust implementations, but leverages V8 JIT compilation to achieve ~400 nanoseconds per iteration on modern hardware.

The VM provides a deterministic, sandboxed execution environment for agent logic. Programs are assembled from text into compact bytecode, then executed with cycle budgets to prevent runaway computation. The included Interpreter class maps natural-language patterns ("factorial of 7", "sum 1 to 100") to bytecode, making it easy to build agent systems where computation is both human-readable and machine-verifiable. A built-in Swarm class enables multi-agent coordination with majority-vote consensus.

Architecture

FLUX.js is the JavaScript implementation of the FLUX bytecode runtime in the SuperInstance ecosystem. It shares the same ISA, A2A protocol, and vocabulary system as the Python and Rust implementations, making bytecode portable across all three runtimes.

Features

• VM — 16 registers, all opcodes, cycle-limited execution
• Assembler — text → bytecode with labels and comments
• Disassembler — bytecode → human-readable listing
• Vocabulary — 10 natural-language patterns
• A2A Agents — multi-agent coordination with messaging
• Swarm — vote and consensus across agents
• ~400 ns/iter on V8 JIT

API / Usage

Assembly Syntax

MOVI R0, 42        # Load immediate
MOV R0, R1         # Copy register
IADD R0, R1, R2    # R0 = R1 + R2
ISUB R0, R1, R2    # R0 = R1 - R2
IMUL R0, R1, R2    # R0 = R1 * R2
IDIV R0, R1, R2    # R0 = R1 / R2
INC R0              # R0++
DEC R0              # R0--
CMP R0, R1          # Compare → flags
JNZ R0, offset      # Jump if not zero
JZ R0, offset       # Jump if zero
JMP offset          # Unconditional jump
PUSH R0 / POP R0    # Stack operations
HALT                # Stop

Natural Language

const { Interpreter } = require('flux-js');
const interp = new Interpreter();

interp.run('factorial of 7');     // { value: 5040, cycles: 24 }
interp.run('sum 1 to 100');       // { value: 5050, cycles: 303 }
interp.run('power of 2 to 10');   // { value: 1024, cycles: 34 }

A2A Swarm

const { A2AAgent, Swarm, assemble } = require('flux-js');

const bc = assemble('MOVI R0, 42\nHALT');
const swarm = new Swarm();
for (let i = 0; i < 5; i++) swarm.add(new A2AAgent(`a${i}`, bc));
swarm.tick();
console.log(swarm.consensus()); // 42

Exports

const { FluxVM, assemble, disassemble, Interpreter, A2AAgent, Swarm } = require('flux-js');

| Export | Description | |--------|-------------| | FluxVM | Bytecode virtual machine | | assemble(text) | Text assembly → Uint8Array | | disassemble(bc) | Bytecode → string[] | | Interpreter | Natural language → execution | | A2AAgent | Single agent with inbox | | Swarm | Multi-agent coordinator |

Built-in Vocabulary

| Pattern | Description | |---------|-------------| | compute X + Y | Addition | | compute X - Y | Subtraction | | compute X * Y | Multiplication | | double X | Double | | square X | Square | | factorial of N | N! | | fibonacci of N | F(N) | | sum A to B | Sum range | | power of BASE to EXP | Exponentiation | | hello | Returns 42 |

Testing

npm install
npm test

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

Same bytecode, different shells. 🦀