flux-vm-js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SuperInstance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# FLUX.js — JavaScript Bytecode VM
+
+[![npm](https://img.shields.io/npm/v/flux-js)](https://www.npmjs.com/package/flux-js)
+[![CI](https://github.com/SuperInstance/flux-js/actions/workflows/ci-node.yml/badge.svg)](https://github.com/SuperInstance/flux-js/actions/workflows/ci-node.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> **FLUX — Fluid Language Universal eXecution**
+> Self-contained FLUX runtime for Node.js and browsers. ~400ns/iter via V8 JIT.
+
+---
+
+## Quick Start
+
+```bash
+npm install flux-js
+```
+
+```javascript
+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](https://github.com/SuperInstance/flux-runtime) and [Rust](https://github.com/SuperInstance/flux-core) 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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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
+
+```bash
+npm install
+npm test
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! See the [SuperInstance Contributing Guide](https://github.com/SuperInstance/SuperInstance/blob/main/CONTRIBUTING.md).
+
+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](https://pypi.org/project/flux-vm/)** | Python | PyPI | `pip install flux-vm` |
+| **[fluxvm](https://crates.io/crates/fluxvm)** | Rust | crates.io | `cargo add fluxvm` |
+| **[flux-js](https://www.npmjs.com/package/flux-js)** | JavaScript | npm | `npm install flux-js` |
+
+Additional implementations: [C](https://github.com/SuperInstance/flux-runtime-c) · [Zig](https://github.com/SuperInstance/flux-zig) · [Go](https://github.com/SuperInstance/flux-swarm) · [Java](https://github.com/SuperInstance/flux-java) · [WASM](https://github.com/SuperInstance/flux-wasm) · [CUDA](https://github.com/SuperInstance/flux-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](https://github.com/SuperInstance/flux-runtime) | Python | Full FLUX runtime: markdown→bytecode, 2037 tests, zero deps |
+| [flux-core](https://github.com/SuperInstance/flux-core) | Rust | Register-based bytecode VM, deterministic agent computation |
+| [flux-js](https://github.com/SuperInstance/flux-js) | JavaScript | FLUX VM for Node.js and browsers, ~400ns/iter |
+| [flux-compiler](https://github.com/SuperInstance/flux-compiler) | Rust/Python | Formal-methods compiler for safety-critical codegen |
+| [flux-vm](https://github.com/SuperInstance/flux-vm) | Rust | Stack-based constraint-checking VM, 50 opcodes, Turing-incomplete |
+
+### PLATO Engine Family
+
+| Repo | Language | Description |
+|------|----------|-------------|
+| [plato-server](https://github.com/SuperInstance/plato-server) | Python | Knowledge tiles, fleet sync via Matrix, HTTP API |
+| [plato-engine-block](https://github.com/SuperInstance/plato-engine-block) | Rust | Original room runtime: no_std + alloc, builder pattern |
+| [plato-engine-block-c](https://github.com/SuperInstance/plato-engine-block-c) | C99 | Embedded reference: zero heap alloc, bare-metal portable |
+| [plato-engine-block-elixir](https://github.com/SuperInstance/plato-engine-block-elixir) | Elixir | BEAM supervision trees, fault tolerance, hot reload |
+| [plato-runtime-kernel](https://github.com/SuperInstance/plato-runtime-kernel) | Rust | Spatial model: tensor grid, batons, assertion traps |
+
+### Constraint / Theory Family
+
+| Repo | Language | Description |
+|------|----------|-------------|
+| [categorical-agents](https://github.com/SuperInstance/categorical-agents) | Rust | Category theory for agent composition (functors, naturality) |
+| [cuda-constraint-engine](https://github.com/SuperInstance/cuda-constraint-engine) | CUDA/C | GPU constraint checking at 1B+ constraints/sec |
+| [grand-pattern-rs](https://github.com/SuperInstance/grand-pattern-rs) | Rust | Fibonacci dual-direction cellular graph architecture |
+| [lau-hodge-theory](https://github.com/SuperInstance/lau-hodge-theory) | Rust | Hodge decomposition, Betti numbers, spectral sequences |
+| [ternary-science](https://github.com/SuperInstance/ternary-science) | Rust | Experimental evidence for ternary intelligence, 5 conservation laws |
+
+### Agent / Infrastructure Family
+
+| Repo | Language | Description |
+|------|----------|-------------|
+| [construct-core](https://github.com/SuperInstance/construct-core) | Rust | Layered trait system: bare-metal → alloc → async agent runtime |
+| [crab](https://github.com/SuperInstance/crab) | Bash | Agent shell for repo entry/leave (MUD-room metaphor) |
+| [exocortex](https://github.com/SuperInstance/exocortex) | Rust | Persistent cognitive substrate, S3-compatible memory |
+| [git-agent](https://github.com/SuperInstance/git-agent) | Python | The repo IS the agent — autonomous lifecycle via Git |
+| [capitaine-1](https://github.com/SuperInstance/capitaine-1) | TypeScript | Git-native repo-agent, Cloudflare Workers heartbeat |
+| [codespace-edge-rd](https://github.com/SuperInstance/codespace-edge-rd) | Research | Codespace→Edge agent lifecycle and yoke transfer protocols |
+| [git-agent-codespace](https://github.com/SuperInstance/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](https://github.com/SuperInstance/AI-Writings) — Philosophy, essays, and design rationale
+- 📦 [PACKAGES.md](https://github.com/SuperInstance/SuperInstance/blob/main/PACKAGES.md) — Full package index
+
+---
+
+## License
+
+MIT
+
+---
+
+*Same bytecode, different shells.* 🦀

package/flux.js

@@ -0,0 +1,641 @@
+/**
+ * FLUX.js — JavaScript Bytecode VM
+ * 
+ * Self-contained FLUX runtime for Node.js and browsers.
+ * Features: VM, assembler, disassembler, vocabulary, A2A agents, swarm.
+ * 
+ * Usage:
+ *   const { FluxVM, assemble, Interpreter } = require('./flux.js');
+ *   const bc = assemble('MOVI R0, 7\nMOVI R1, 1\nIMUL R1, R1, R0\nDEC R0\nJNZ R0, -10\nHALT');
+ *   const vm = new FluxVM(bc);
+ *   vm.execute();
+ *   console.log(vm.reg(1)); // 5040
+ */
+
+'use strict';
+
+// ─── Opcodes ──────────────────────────────────────────────────────────────
+
+const OP = {
+  NOP:0x00, MOV:0x01, LOAD:0x02, STORE:0x03,
+  JMP:0x04, JZ:0x05, JNZ:0x06, CALL:0x07,
+  IADD:0x08, ISUB:0x09, IMUL:0x0A, IDIV:0x0B,
+  IMOD:0x0C, INEG:0x0D, INC:0x0E, DEC:0x0F,
+  IAND:0x10, IOR:0x11, IXOR:0x12, INOT:0x13,
+  ISHL:0x14, ISHR:0x15,
+  PUSH:0x20, POP:0x21, DUP:0x22,
+  RET:0x28, MOVI:0x2B, CMP:0x2D,
+  JE:0x2E, JNE:0x2F,
+  FADD:0x40, FSUB:0x41, FMUL:0x42, FDIV:0x43,
+  TELL:0x60, ASK:0x61, DELEGATE:0x62, BROADCAST:0x66,
+  HALT:0x80, YIELD:0x81
+};
+
+const MNEMONIC = Object.fromEntries(Object.entries(OP).map(([k,v])=>[v,k]));
+
+// ─── VM ───────────────────────────────────────────────────────────────────
+
+class FluxVM {
+  /**
+   * Create a FLUX bytecode VM.
+   * @param {Uint8Array|ArrayBuffer} bytecode
+   * @param {number} [maxCycles=10_000_000]
+   */
+  constructor(bytecode, maxCycles = 10_000_000) {
+    this.gp = new Int32Array(16);  // 16 general-purpose registers
+    this.pc = 0;
+    this.halted = false;
+    this.cycles = 0;
+    this.stack = [];
+    this.bc = bytecode instanceof Uint8Array ? bytecode : new Uint8Array(bytecode);
+    this.maxCycles = maxCycles;
+    this.error = null;
+    this._flagZero = false;
+    this._flagSign = false;
+  }
+
+  /** Read register */
+  reg(idx) { return this.gp[idx] || 0; }
+
+  /** Read unsigned byte */
+  _u8() { return this.bc[this.pc++]; }
+
+  /** Update condition flags based on an arithmetic result (matches Python/Rust) */
+  _setFlags(result) {
+    this._flagZero = (result === 0);
+    this._flagSign = (result < 0);
+  }
+
+  /** Read signed 16-bit */
+  _i16() {
+    const lo = this.bc[this.pc++];
+    const hi = this.bc[this.pc++];
+    const val = lo | (hi << 8);
+    return val >= 32768 ? val - 65536 : val;
+  }
+
+  /**
+   * Execute until HALT or maxCycles.
+   * @returns {FluxVM} this (for chaining)
+   */
+  execute() {
+    this.halted = false;
+    this.cycles = 0;
+    this.error = null;
+    try {
+      while (!this.halted && this.pc < this.bc.length && this.cycles < this.maxCycles) {
+        const op = this._u8();
+        this.cycles++;
+        switch (op) {
+          case 0x80: this.halted = true; break;
+          case 0x00: break; // NOP
+          case 0x01: { const d=this._u8(),s=this._u8(); this.gp[d]=this.gp[s]; break; } // MOV
+          case 0x2B: { const d=this._u8(); this.gp[d]=this._i16(); break; } // MOVI
+          // 3-operand arithmetic: [op][rd][rs1][rs2]
+          case 0x08: { const d=this._u8(),a=this._u8(),b=this._u8(); const r=(this.gp[a]+this.gp[b])|0; this.gp[d]=r; this._setFlags(r); break; } // IADD
+          case 0x09: { const d=this._u8(),a=this._u8(),b=this._u8(); const r=(this.gp[a]-this.gp[b])|0; this.gp[d]=r; this._setFlags(r); break; } // ISUB
+          case 0x0A: { const d=this._u8(),a=this._u8(),b=this._u8(); const r=(this.gp[a]*this.gp[b])|0; this.gp[d]=r; this._setFlags(r); break; } // IMUL
+          case 0x0B: { const d=this._u8(),a=this._u8(),b=this._u8();
+            if(this.gp[b]===0) throw new Error('Division by zero');
+            this.gp[d]=(this.gp[a]/this.gp[b])|0; this._setFlags(this.gp[d]); break; } // IDIV
+          case 0x0C: { const d=this._u8(),a=this._u8(),b=this._u8();
+            if(this.gp[b]===0) throw new Error('Modulo by zero');
+            this.gp[d]=(this.gp[a]%this.gp[b])|0; this._setFlags(this.gp[d]); break; } // IMOD
+          case 0x0E: { const r=this._u8(); const v=(this.gp[r]+1)|0; this.gp[r]=v; this._setFlags(v); break; } // INC
+          case 0x0F: { const r=this._u8(); const v=(this.gp[r]-1)|0; this.gp[r]=v; this._setFlags(v); break; } // DEC
+          // FIX: PUSH/POP now use 0x20/0x21 (was 0x10/0x11)
+          case 0x20: this.stack.push(this.gp[this._u8()]); break; // PUSH
+          case 0x21: this.gp[this._u8()]=this.stack.pop()||0; break; // POP
+          case 0x22: { if(this.stack.length>0){ const v=this.stack[this.stack.length-1]; this.stack.push(v);} break; } // DUP
+          case 0x04: { const _r=this._u8(),off=this._i16(); this.pc=(this.pc+off)&0xFFFFFFFF; break; } // JMP
+          case 0x05: { const r=this._u8(),off=this._i16(); if(this.gp[r]===0) this.pc=(this.pc+off)&0xFFFFFFFF; break; } // JZ
+          case 0x06: { const r=this._u8(),off=this._i16(); if(this.gp[r]!==0) this.pc=(this.pc+off)&0xFFFFFFFF; break; } // JNZ
+          case 0x07: { const _r=this._u8(),off=this._i16(); this.stack.push(this.pc); this.pc=(this.pc+off)&0xFFFFFFFF; break; } // CALL
+          case 0x28: { const _r=this._u8(),_p=this._u8(); if(this.stack.length>0){ this.pc=this.stack.pop(); } break; } // RET
+          case 0x2D: { const a=this._u8(),b=this._u8();
+            this._flagZero = this.gp[a]===this.gp[b];
+            this._flagSign = this.gp[a]<this.gp[b];
+            break; } // CMP
+          case 0x2E: { const _r=this._u8(),off=this._i16(); if(this._flagZero) this.pc=(this.pc+off)&0xFFFFFFFF; break; } // JE
+          case 0x2F: { const _r=this._u8(),off=this._i16(); if(!this._flagZero) this.pc=(this.pc+off)&0xFFFFFFFF; break; } // JNE
+          case 0x10: { const d=this._u8(),a=this._u8(),b=this._u8(); const r=this.gp[a]&this.gp[b]; this.gp[d]=r; this._setFlags(r); break; } // IAND
+          case 0x11: { const d=this._u8(),a=this._u8(),b=this._u8(); const r=this.gp[a]|this.gp[b]; this.gp[d]=r; this._setFlags(r); break; } // IOR
+          case 0x12: { const d=this._u8(),a=this._u8(),b=this._u8(); const r=this.gp[a]^this.gp[b]; this.gp[d]=r; this._setFlags(r); break; } // IXOR
+          case 0x13: { const d=this._u8(),s=this._u8(); const r=~this.gp[s]; this.gp[d]=r; this._setFlags(r); break; } // INOT
+          case 0x14: { const d=this._u8(),a=this._u8(),b=this._u8(); const r=this.gp[a]<<(this.gp[b]&0x1f); this.gp[d]=r; this._setFlags(r); break; } // ISHL
+          case 0x15: { const d=this._u8(),a=this._u8(),b=this._u8(); const r=this.gp[a]>>(this.gp[b]&0x1f); this.gp[d]=r; this._setFlags(r); break; } // ISHR
+          case 0x81: break; // YIELD
+          // A2A stubs (Format G: [op][len:u16][data:len]) — experimental, consistent with Python/Rust
+          case 0x60: case 0x61: case 0x62: case 0x66: {
+            const _len = this._u8() | (this._u8() << 8);
+            this.pc += _len; // skip variable data
+            break;
+          }
+          default: throw new Error(`Unknown opcode: 0x${op.toString(16).padStart(2,'0')}`);
+        }
+      }
+    } catch (e) { this.error = e.message; }
+    return this;
+  }
+
+  /** Pretty-print register state */
+  dump() {
+    const regs = [];
+    for (let i = 0; i < 16; i++) if (this.gp[i] !== 0) regs.push(`R${i}=${this.gp[i]}`);
+    return `PC=${this.pc} cycles=${this.cycles} halted=${this.halted} [${regs.join(' ')}]`;
+  }
+}
+
+// ─── Assembler ────────────────────────────────────────────────────────────
+
+/**
+ * Assemble FLUX text to bytecode.
+ * Supports labels (label:), comments (// or ;), all instruction formats.
+ * @param {string} text
+ * @returns {Uint8Array}
+ */
+function assemble(text) {
+  const labels = {};
+  const instructions = [];
+
+  // Pass 1: collect labels and calculate sizes
+  let pc = 0;
+  for (const rawLine of text.split('\n')) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('//') || line.startsWith(';')) continue;
+    if (line.includes(':')) {
+      const [labelPart, ...rest] = line.split(':');
+      labels[labelPart.trim()] = pc;
+      line = rest.join(':').trim();
+      if (!line) continue;
+    }
+    const parts = line.replace(/,/g, ' ').split(/\s+/);
+    const mn = parts[0].toUpperCase();
+    instructions.push({ parts, pc });
+    
+    // Size calculation
+    if (mn in OP) {
+      if (['HALT','NOP','DUP','YIELD'].includes(mn)) pc += 1;
+      else if (['INC','DEC','PUSH','POP','INEG','INOT'].includes(mn)) pc += 2;
+      else if (['MOV','LOAD','STORE','CMP'].includes(mn)) pc += 3;
+      else if (['IADD','ISUB','IMUL','IDIV','IMOD','IAND','IOR','IXOR','ISHL','ISHR'].includes(mn)) pc += 4;
+      else if (['MOVI','JMP','JZ','JNZ','CALL','JE','JNE'].includes(mn)) pc += 4;
+      else if (mn === 'RET') pc += 3;
+    }
+  }
+
+  // Pass 2: emit bytecode
+  const bc = [];
+  const resolveValue = (token, currentPc) => {
+    token = token.trim();
+    const num = parseInt(token);
+    if (!isNaN(num)) return num;
+    if (token in labels) return labels[token] - currentPc;
+    throw new Error(`Cannot resolve: ${token}`);
+  };
+
+  for (const { parts, pc: instPc } of instructions) {
+    const mn = parts[0].toUpperCase();
+    if (!(mn in OP)) continue;
+    const op = OP[mn];
+
+    if (['HALT','NOP','DUP','YIELD'].includes(mn)) {
+      bc.push(op);
+    } else if (['INC','DEC','PUSH','POP'].includes(mn)) {
+      bc.push(op, parseInt(parts[1].slice(1)));
+    } else if (['MOV','LOAD','STORE','CMP'].includes(mn)) {
+      bc.push(op, parseInt(parts[1].slice(1)), parseInt(parts[2].slice(1)));
+    } else if (['IADD','ISUB','IMUL','IDIV','IMOD','IAND','IOR','IXOR','ISHL','ISHR'].includes(mn)) {
+      bc.push(op, parseInt(parts[1].slice(1)), parseInt(parts[2].slice(1)),
+              parts.length > 3 ? parseInt(parts[3].slice(1)) : parseInt(parts[1].slice(1)));
+    } else if (mn === 'MOVI') {
+      bc.push(op, parseInt(parts[1].slice(1)));
+      const v = resolveValue(parts[2], bc.length + 1);
+      bc.push(v & 0xFF, (v >> 8) & 0xFF);
+    } else if (['JMP','JZ','JNZ','CALL','JE','JNE'].includes(mn)) {
+      bc.push(op, parseInt(parts[1] ? parts[1].slice(1) : '0') || 0);
+      const labelOrOff = parts[2] || parts[1];
+      const v = isNaN(parseInt(labelOrOff)) ? resolveValue(labelOrOff, bc.length + 2) : parseInt(labelOrOff);
+      bc.push(v & 0xFF, (v >> 8) & 0xFF);
+    } else if (mn === 'RET') {
+      bc.push(op, 0, 0);
+    }
+  }
+
+  return new Uint8Array(bc);
+}
+
+// ─── Disassembler ─────────────────────────────────────────────────────────
+
+/**
+ * Disassemble bytecode to human-readable text.
+ * @param {Uint8Array} bytecode
+ * @returns {string[]}
+ */
+function disassemble(bytecode) {
+  const lines = [];
+  let pc = 0;
+  const bc = bytecode instanceof Uint8Array ? bytecode : new Uint8Array(bytecode);
+  
+  while (pc < bc.length) {
+    const addr = pc;
+    const op = bc[pc++];
+    const mn = MNEMONIC[op] || `??? (0x${op.toString(16).padStart(2,'0')})`;
+
+    if ([0x80, 0x00, 0x22, 0x81].includes(op)) {
+      lines.push(`${addr.toString(16).padStart(4,'0')}: ${mn}`);
+    } else if ([0x0E, 0x0F, 0x20, 0x21].includes(op)) {
+      lines.push(`${addr.toString(16).padStart(4,'0')}: ${mn} R${bc[pc++]}`);
+    } else if ([0x01, 0x02, 0x03, 0x2D].includes(op)) {
+      lines.push(`${addr.toString(16).padStart(4,'0')}: ${mn} R${bc[pc++]}, R${bc[pc++]}`);
+    } else if ([0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x10, 0x11, 0x12, 0x14, 0x15].includes(op)) {
+      lines.push(`${addr.toString(16).padStart(4,'0')}: ${mn} R${bc[pc++]}, R${bc[pc++]}, R${bc[pc++]}`);
+    } else if ([0x2B, 0x04, 0x05, 0x06, 0x07, 0x2E, 0x2F].includes(op)) {
+      const rd = bc[pc++];
+      const val = bc[pc] | (bc[pc+1] << 8) | (bc[pc+1] >= 128 ? -65536 : 0);
+      pc += 2;
+      lines.push(`${addr.toString(16).padStart(4,'0')}: ${mn} R${rd}, ${val}`);
+    } else if (op === 0x28) {
+      pc += 2; // RET has 2 padding bytes
+      lines.push(`${addr.toString(16).padStart(4,'0')}: ${mn}`);
+    } else {
+      lines.push(`${addr.toString(16).padStart(4,'0')}: ${mn}`);
+    }
+  }
+  return lines;
+}
+
+// ─── Vocabulary ───────────────────────────────────────────────────────────
+
+class VocabEntry {
+  /**
+   * @param {RegExp|string} pattern 
+   * @param {string|function} asmTemplate 
+   * @param {string} name 
+   * @param {number} resultReg 
+   */
+  constructor(pattern, asmTemplate, name, resultReg = 0) {
+    this.pattern = typeof pattern === 'string' ? new RegExp(pattern, 'i') : pattern;
+    this.asmTemplate = asmTemplate;
+    this.name = name;
+    this.resultReg = resultReg;
+  }
+
+  /**
+   * Match text against pattern
+   * @param {string} text 
+   * @returns {Array|null} captured groups or null
+   */
+  match(text) {
+    const m = text.match(this.pattern);
+    return m ? m.slice(1) : null;
+  }
+}
+
+class Vocabulary {
+  constructor() {
+    this.entries = [];
+  }
+
+  /**
+   * Add a vocabulary entry
+   * @param {VocabEntry} entry 
+   */
+  register(entry) {
+    this.entries.push(entry);
+  }
+
+  /**
+   * Find first matching entry for text
+   * @param {string} text 
+   * @returns {VocabEntry|null}
+   */
+  findMatch(text) {
+    for (const entry of this.entries) {
+      if (entry.match(text) !== null) {
+        return entry;
+      }
+    }
+    return null;
+  }
+}
+
+class VocabInterpreter {
+  constructor() {
+    this.vocab = new Vocabulary();
+    this.assembler = assemble; // Use existing assemble function
+    this.vm = null;
+    
+    // Register built-in entries
+    this.vocab.register(new VocabEntry(
+      /^compute\s+(\d+)\s*\+\s*(\d+)$/i,
+      (a, b) => `MOVI R0, ${a}\nMOVI R1, ${b}\nIADD R0, R0, R1\nHALT`,
+      'add',
+      0
+    ));
+    this.vocab.register(new VocabEntry(
+      /^compute\s+(\d+)\s*\*\s*(\d+)$/i,
+      (a, b) => `MOVI R0, ${a}\nMOVI R1, ${b}\nIMUL R0, R0, R1\nHALT`,
+      'mul',
+      0
+    ));
+    this.vocab.register(new VocabEntry(
+      /^factorial\s+of\s+(\d+)$/i,
+      (n) => `MOVI R0, ${n}\nMOVI R1, 1\nIMUL R1, R1, R0\nDEC R0\nJNZ R0, -10\nHALT`,
+      'factorial',
+      1
+    ));
+    this.vocab.register(new VocabEntry(
+      /^double\s+(\d+)$/i,
+      (n) => `MOVI R0, ${n}\nIADD R0, R0, R0\nHALT`,
+      'double',
+      0
+    ));
+    this.vocab.register(new VocabEntry(
+      /^square\s+(\d+)$/i,
+      (n) => `MOVI R0, ${n}\nIMUL R0, R0, R0\nHALT`,
+      'square',
+      0
+    ));
+    this.vocab.register(new VocabEntry(
+      /^hello$/i,
+      () => `MOVI R0, 42\nHALT`,
+      'hello',
+      0
+    ));
+  }
+
+  /**
+   * Run text through vocabulary interpreter
+   * @param {string} text 
+   * @returns {{ value: number|null, message: string, cycles: number }}
+   */
+  run(text) {
+    const trimmed = text.trim();
+    const entry = this.vocab.findMatch(trimmed);
+    
+    if (!entry) {
+      return { value: null, message: `No vocabulary match for: ${trimmed.slice(0, 80)}`, cycles: 0 };
+    }
+    
+    const args = entry.match(trimmed).map(Number);
+    let asmText;
+    if (typeof entry.asmTemplate === 'function') {
+      asmText = entry.asmTemplate(...args);
+    } else {
+      asmText = entry.asmTemplate;
+    }
+    
+    try {
+      const bc = this.assembler(asmText);
+      this.vm = new FluxVM(bc);
+      this.vm.execute();
+      return { 
+        value: this.vm.reg(entry.resultReg), 
+        message: `OK (${this.vm.cycles} cycles)`, 
+        cycles: this.vm.cycles 
+      };
+    } catch (e) {
+      return { value: null, message: `Error: ${e.message}`, cycles: 0 };
+    }
+  }
+}
+
+const VOCAB = [
+  { pattern: /^compute\s+(\d+)\s*\+\s*(\d+)$/i, name: 'add',
+    asm: (a,b) => `MOVI R0, ${a}\nMOVI R1, ${b}\nIADD R0, R0, R1\nHALT`, reg: 0 },
+  { pattern: /^compute\s+(\d+)\s*-\s*(\d+)$/i, name: 'sub',
+    asm: (a,b) => `MOVI R0, ${a}\nMOVI R1, ${b}\nISUB R0, R0, R1\nHALT`, reg: 0 },
+  { pattern: /^compute\s+(\d+)\s*\*\s*(\d+)$/i, name: 'mul',
+    asm: (a,b) => `MOVI R0, ${a}\nMOVI R1, ${b}\nIMUL R0, R0, R1\nHALT`, reg: 0 },
+  { pattern: /^double\s+(\d+)$/i, name: 'double',
+    asm: (a) => `MOVI R0, ${a}\nIADD R0, R0, R0\nHALT`, reg: 0 },
+  { pattern: /^square\s+(\d+)$/i, name: 'square',
+    asm: (a) => `MOVI R0, ${a}\nIMUL R0, R0, R0\nHALT`, reg: 0 },
+  { pattern: /^factorial\s+of\s+(\d+)$/i, name: 'factorial',
+    asm: (n) => `MOVI R0, ${n}\nMOVI R1, 1\nIMUL R1, R1, R0\nDEC R0\nJNZ R0, -10\nHALT`, reg: 1 },
+  { pattern: /^fibonacci\s+of\s+(\d+)$/i, name: 'fibonacci',
+    asm: (n) => `MOVI R0, 0\nMOVI R1, 1\nMOVI R2, ${n}\nMOV R3, R1\nIADD R1, R1, R0\nMOV R0, R3\nDEC R2\nJNZ R2, -16\nHALT`, reg: 0 },
+  { pattern: /^sum\s+(\d+)\s+to\s+(\d+)$/i, name: 'sum',
+    asm: (a,b) => `MOVI R0, 0\nMOVI R1, ${b}\nIADD R0, R0, R1\nDEC R1\nJNZ R1, -10\nHALT`, reg: 0 },
+  { pattern: /^power\s+of\s+(\d+)\s+to\s+(\d+)$/i, name: 'power',
+    asm: (base,exp) => `MOVI R0, 1\nMOVI R1, ${base}\nMOVI R2, ${exp}\nIMUL R0, R0, R1\nDEC R2\nJNZ R2, -10\nHALT`, reg: 0 },
+  { pattern: /^hello$/i, name: 'hello',
+    asm: () => `MOVI R0, 42\nHALT`, reg: 0 },
+];
+
+// ─── Interpreter ──────────────────────────────────────────────────────────
+
+class Interpreter {
+  constructor() {
+    this.vocab = [...VOCAB];
+  }
+
+  /**
+   * Interpret natural language text and execute.
+   * @param {string} text
+   * @returns {{ value: number|null, message: string, cycles: number }}
+   */
+  run(text) {
+    const trimmed = text.trim();
+
+    // Try vocabulary
+    for (const entry of this.vocab) {
+      const m = trimmed.match(entry.pattern);
+      if (m) {
+        const args = m.slice(1).map(Number);
+        const asmText = entry.asm(...args);
+        try {
+          const bc = assemble(asmText);
+          const vm = new FluxVM(bc);
+          vm.execute();
+          return { value: vm.reg(entry.reg), message: `OK (${vm.cycles} cycles)`, cycles: vm.cycles };
+        } catch (e) {
+          return { value: null, message: `Error: ${e.message}`, cycles: 0 };
+        }
+      }
+    }
+
+    // Try direct assembly
+    const firstWord = trimmed.split(/\s+/)[0]?.toUpperCase();
+    if (firstWord && firstWord in OP) {
+      try {
+        const bc = assemble(trimmed);
+        const vm = new FluxVM(bc);
+        vm.execute();
+        return { value: vm.reg(0), message: `OK (${vm.cycles} cycles, direct asm)`, cycles: vm.cycles };
+      } catch (e) {
+        return { value: null, message: `Error: ${e.message}`, cycles: 0 };
+      }
+    }
+
+    return { value: null, message: `No match for: ${trimmed.slice(0, 80)}`, cycles: 0 };
+  }
+}
+
+// ─── A2A Agents ───────────────────────────────────────────────────────────
+
+class A2AAgent {
+  constructor(id, bytecode, role = 'worker') {
+    this.id = id;
+    this.vm = new FluxVM(bytecode);
+    this.role = role;
+    this.trust = 1.0;
+    this.inbox = [];
+    this.generation = 0;
+  }
+
+  step() {
+    this.vm.execute();
+    this.generation++;
+    return this.vm.cycles;
+  }
+
+  tell(other, payload) {
+    other.inbox.push({ from: this.id, type: 'TELL', payload, gen: this.generation, trust: this.trust });
+  }
+
+  ask(other) {
+    other.inbox.push({ from: this.id, type: 'ASK', gen: this.generation });
+    return other.vm.halted ? other.vm.reg(0) : null;
+  }
+}
+
+class Swarm {
+  constructor() { this.agents = new Map(); }
+
+  add(agent) { this.agents.set(agent.id, agent); }
+
+  tick() {
+    let total = 0;
+    for (const a of this.agents.values()) total += a.step();
+    return total;
+  }
+
+  vote(reg = 0) {
+    const counts = {};
+    for (const a of this.agents.values()) {
+      if (a.vm.halted) {
+        const v = a.vm.reg(reg);
+        counts[v] = (counts[v] || 0) + 1;
+      }
+    }
+    return counts;
+  }
+
+  consensus(reg = 0) {
+    const counts = this.vote(reg);
+    if (!Object.keys(counts).length) return null;
+    return Number(Object.entries(counts).sort((a,b) => b[1]-a[1])[0][0]);
+  }
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────
+
+module.exports = { 
+  FluxVM, 
+  assemble, 
+  disassemble, 
+  Interpreter, 
+  A2AAgent, 
+  Swarm, 
+  VocabEntry, 
+  Vocabulary, 
+  VocabInterpreter,
+  OP, 
+  VOCAB 
+};
+
+// ─── CLI Demo ─────────────────────────────────────────────────────────────
+
+if (typeof require !== 'undefined' && require.main === module) {
+  console.log('╔══════════════════════════════════════════════════╗');
+  console.log('║   FLUX.js — JavaScript Bytecode VM              ║');
+  console.log('║   SuperInstance / Oracle1                        ║');
+  console.log('╚══════════════════════════════════════════════════╝\n');
+
+  const interp = new Interpreter();
+  console.log(`  ${interp.vocab.length} vocabulary patterns loaded\n`);
+
+  // Arithmetic
+  console.log('=== Arithmetic ===');
+  for (const expr of ['compute 3 + 4', 'compute 10 * 5', 'double 21', 'square 8']) {
+    const r = interp.run(expr);
+    console.log(`  ${expr} → ${r.value}`);
+  }
+
+  // Loops
+  console.log('\n=== Loops ===');
+  for (const expr of ['factorial of 7', 'fibonacci of 12', 'sum 1 to 100', 'power of 2 to 10']) {
+    const r = interp.run(expr);
+    console.log(`  ${expr} → ${r.value} (${r.cycles} cycles)`);
+  }
+
+  // Assembler
+  console.log('\n=== Assembler ===');
+  const bc = assemble('MOVI R0, 7\nMOVI R1, 1\nIMUL R1, R1, R0\nDEC R0\nJNZ R0, -10\nHALT');
+  const vm = new FluxVM(bc);
+  vm.execute();
+  console.log(`  factorial(7) bytecode: ${Array.from(bc).map(b=>b.toString(16).padStart(2,'0')).join(' ')}`);
+  console.log(`  Result: R1 = ${vm.reg(1)}`);
+
+  // Disassembler
+  console.log('\n=== Disassembler ===');
+  for (const line of disassemble(bc)) console.log(`  ${line}`);
+
+  // Swarm
+  console.log('\n=== A2A Swarm ===');
+  const swarm = new Swarm();
+  const agentBc = assemble('MOVI R0, 42\nHALT');
+  for (let i = 0; i < 5; i++) {
+    swarm.add(new A2AAgent(`agent-${i}`, agentBc, ['worker','scout','navigator'][i%3]));
+  }
+  const totalCycles = swarm.tick();
+  console.log(`  5 agents, ${totalCycles} cycles, consensus: ${swarm.consensus()}`);
+
+  // Benchmark
+  console.log('\n=== Benchmark ===');
+  const N = 100000;
+  const t0 = Date.now();
+  for (let i = 0; i < N; i++) new FluxVM(bc).execute();
+  const elapsed = Date.now() - t0;
+  console.log(`  factorial(7) x ${N.toLocaleString()}: ${elapsed} ms | ${(elapsed*1e6/N).toFixed(0)} ns/iter`);
+
+  console.log('\n✓ FLUX.js all systems operational!');
+
+  // Test the new vocabulary interpreter
+  console.log('\n=== Testing VocabInterpreter ===');
+  const vocabInterp = new VocabInterpreter();
+  
+  // Test compute A + B
+  const addResult = vocabInterp.run('compute 3 + 4');
+  console.assert(addResult.value === 7, `Expected 7, got ${addResult.value}`);
+  console.log(`  compute 3 + 4 → ${addResult.value} (${addResult.message})`);
+  
+  // Test compute A * B
+  const mulResult = vocabInterp.run('compute 5 * 6');
+  console.assert(mulResult.value === 30, `Expected 30, got ${mulResult.value}`);
+  console.log(`  compute 5 * 6 → ${mulResult.value} (${mulResult.message})`);
+  
+  // Test factorial
+  const factResult = vocabInterp.run('factorial of 5');
+  console.assert(factResult.value === 120, `Expected 120, got ${factResult.value}`);
+  console.log(`  factorial of 5 → ${factResult.value} (${factResult.message})`);
+  
+  // Test double
+  const doubleResult = vocabInterp.run('double 21');
+  console.assert(doubleResult.value === 42, `Expected 42, got ${doubleResult.value}`);
+  console.log(`  double 21 → ${doubleResult.value} (${addResult.message})`);
+  
+  // Test square
+  const squareResult = vocabInterp.run('square 8');
+  console.assert(squareResult.value === 64, `Expected 64, got ${squareResult.value}`);
+  console.log(`  square 8 → ${squareResult.value} (${squareResult.message})`);
+  
+  // Test hello
+  const helloResult = vocabInterp.run('hello');
+  console.assert(helloResult.value === 42, `Expected 42, got ${helloResult.value}`);
+  console.log(`  hello → ${helloResult.value} (${helloResult.message})`);
+  
+  console.log('\n✓ All VocabInterpreter tests passed!');
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "flux-vm-js",
+  "version": "1.0.0",
+  "description": "FLUX.js — JavaScript Bytecode VM. Self-contained FLUX runtime for Node.js and browsers.",
+  "main": "flux.js",
+  "author": "SuperInstance",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SuperInstance/flux-js.git"
+  },
+  "keywords": [
+    "flux",
+    "vm",
+    "bytecode",
+    "runtime",
+    "virtual-machine",
+    "interpreter",
+    "assembly",
+    "superinstance"
+  ],
+  "homepage": "https://github.com/SuperInstance/flux-js#readme",
+  "bugs": {
+    "url": "https://github.com/SuperInstance/flux-js/issues"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "flux.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "vitest": "^3.2.1"
+  }
+}