superinstance-flux-runtime 1.0.0

data/lib/superinstance/flux-runtime/loader.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Flux
+  # Binary loader for FLUX bytecode files
+  class Loader
+    FLUX_MAGIC = 'FLUX'.b
+
+    # Load a FLUX bytecode file
+    # Returns raw bytecode, stripping the FLUX header if present
+    def load_file(path)
+      data = File.binread(path)
+
+      if data.start_with?(FLUX_MAGIC)
+        strip_header(data)
+      else
+        data
+      end
+    end
+
+    # Check if file has FLUX header
+    def has_header?(path)
+      data = File.binread(path, 4)
+      data == FLUX_MAGIC
+    end
+
+    # Parse header information
+    def parse_header(path)
+      data = File.binread(path)
+
+      unless data.start_with?(FLUX_MAGIC)
+        return nil
+      end
+
+      {
+        magic: data[0..3],
+        version_major: data.getbyte(4) | (data.getbyte(5) << 8),
+        version_minor: data.getbyte(6) | (data.getbyte(7) << 8),
+        flags: data.getbyte(8) | (data.getbyte(9) << 8),
+        entry_point: data.getbyte(10) | (data.getbyte(11) << 8) |
+                    (data.getbyte(12) << 16) | (data.getbyte(13) << 24),
+        reserved: data[14..17]
+      }
+    end
+
+    private
+
+    def strip_header(data)
+      # FLUX header is 16 bytes
+      # Magic (4) + Version (2) + Flags (2) + Entry point (4) + Reserved (4)
+      return data[16..] if data.bytesize > 16
+
+      data
+    end
+  end
+end

data/lib/superinstance/flux-runtime/opcode.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative 'exceptions'
+
+module Flux
+  # Opcode registry mapping opcode byte values to method names
+  # and providing all core opcode implementations
+  module OpcodeRegistry
+    OPCODE_CLASSES = {
+      # Control Flow (0x00-0x0F)
+      0x00 => :Halt,
+      0x01 => :Nop,
+      0x02 => :Ret,
+      0x03 => :Jump,
+      0x04 => :JumpIf,
+      0x05 => :JumpIfNot,
+      0x06 => :Call,
+      0x07 => :CallIndirect,
+      0x08 => :Yield,
+      0x09 => :Panic,
+      0x0A => :Unreachable,
+
+      # Stack Operations (0x10-0x1F)
+      0x10 => :Push,
+      0x11 => :Pop,
+      0x12 => :Dup,
+      0x13 => :Swap,
+
+      # Integer Arithmetic (0x20-0x3F)
+      0x20 => :IMov,
+      0x21 => :IAdd,
+      0x22 => :ISub,
+      0x23 => :IMul,
+      0x24 => :IDiv,
+      0x25 => :IMod,
+      0x26 => :INeg,
+      0x27 => :IAbs,
+      0x28 => :IInc,
+      0x29 => :IDec,
+      0x2A => :IMin,
+      0x2B => :IMax,
+      0x2C => :IAnd,
+      0x2D => :IOr,
+      0x2E => :IXor,
+      0x2F => :IShl,
+      0x30 => :IShr,
+      0x31 => :INot,
+      0x32 => :ICmpEq,
+      0x33 => :ICmpNe,
+      0x34 => :ICmpLt,
+      0x35 => :ICmpLe,
+      0x36 => :ICmpGt,
+      0x37 => :ICmpGe,
+
+      # Float Arithmetic (0x40-0x5F)
+      0x40 => :FMov,
+      0x41 => :FAdd,
+      0x42 => :FSub,
+      0x43 => :FMul,
+      0x44 => :FDiv,
+      0x45 => :FMod,
+      0x46 => :FNeg,
+      0x47 => :FAbs,
+      0x48 => :FSqrt,
+      0x49 => :FFloor,
+      0x4A => :FCeil,
+      0x4B => :FRound,
+      0x4C => :FMin,
+      0x4D => :FMax,
+      0x4E => :FSin,
+      0x4F => :FCos,
+      0x50 => :FExp,
+      0x51 => :FLog,
+      0x52 => :FClamp,
+      0x53 => :FLerp,
+      0x54 => :FCmpEq,
+      0x55 => :FCmpNe,
+      0x56 => :FCmpLt,
+      0x57 => :FCmpLe,
+      0x58 => :FCmpGt,
+      0x59 => :FCmpGe,
+
+      # Conversions (0x60-0x6F)
+      0x60 => :IToF,
+      0x61 => :FToI,
+      0x62 => :BToI,
+      0x63 => :IToB,
+
+      # Memory Operations (0x70-0x7F)
+      0x70 => :Load8,
+      0x71 => :Load16,
+      0x72 => :Load32,
+      0x73 => :Load64,
+      0x74 => :Store8,
+      0x75 => :Store16,
+      0x76 => :Store32,
+      0x77 => :Store64,
+      0x78 => :LoadAddr,
+      0x79 => :StackAlloc,
+
+      # Agent-to-Agent Communication (0x80-0x8F)
+      0x80 => :ASend,
+      0x81 => :ARecv,
+      0x82 => :AAsk,
+      0x83 => :ATell,
+      0x84 => :ADelegate,
+      0x85 => :ABroadcast,
+      0x86 => :ASubscribe,
+      0x87 => :AWait,
+      0x88 => :ATrust,
+      0x89 => :AVerify,
+
+      # Type/Meta Operations (0x90-0x9F)
+      0x90 => :Cast,
+      0x91 => :SizeOf,
+      0x92 => :TypeOf,
+
+      # Bitwise Operations (0xA0-0xAF)
+      0xA0 => :BAnd,
+      0xA1 => :BOr,
+      0xA2 => :BXor,
+      0xA3 => :BShl,
+      0xA4 => :BShr,
+      0xA5 => :BNot,
+
+      # Vector/SIMD Operations (0xB0-0xBF)
+      0xB0 => :VLoad,
+      0xB1 => :VStore,
+      0xB2 => :VAdd,
+      0xB3 => :VMul,
+      0xB4 => :VDot
+    }.freeze
+
+    OPCODE_NAMES = OPCODE_CLASSES.transform_values(&:to_s).freeze
+
+    # Get opcode name from byte
+    def self.opcode_name(opcode_byte)
+      OPCODE_NAMES[opcode_byte] || "Unknown_0x#{opcode_byte.to_s(16).upcase}"
+    end
+  end
+end

data/lib/superinstance/flux-runtime/runtime/agent.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative '../flux_vm'
+
+module Flux
+  module Runtime
+    # Agent shell that wraps a FluxVM and provides method_missing
+    # for PLATO-based capability lookup
+    #
+    # @example
+    #   agent = Flux::Runtime::Agent.new
+    #   agent.load(bytecode)
+    #   agent.run
+    #
+    # @example with PLATO
+    #   client = PLATO::Client.new
+    #   agent = Flux::Runtime::Agent.new(plato_client: client, vessel_id: 'my-agent')
+    #
+    #   # Unknown method triggers PLATO lookup
+    #   result = agent.learned_capability(arg1, arg2)
+    #
+    class Agent
+      attr_reader :vm, :vessel_id
+
+      def initialize(plato_client: nil, vessel_id: nil)
+        @vm = FluxVM.new
+        @plato = plato_client
+        @vessel_id = vessel_id
+        @capabilities = {}
+      end
+
+      # Load bytecode into the VM
+      def load(bytecode)
+        @vm.load(bytecode)
+        self
+      end
+
+      # Run the VM
+      def run(max_cycles: nil)
+        @vm.run(max_cycles: max_cycles)
+        self
+      end
+
+      # Step one instruction
+      def step
+        @vm.step
+        self
+      end
+
+      # Reset the VM
+      def reset
+        @vm.reset
+        self
+      end
+
+      # Get current state
+      def state
+        @vm.state
+      end
+
+      # Get register values
+      def regs
+        @vm.regs
+      end
+
+      # Get execution stats
+      def stats
+        @vm.stats
+      end
+
+      # Delegate unknown methods to VM if they exist there
+      # Otherwise, look up in PLATO
+      def method_missing(method_name, *args, &block)
+        # Check if it's a VM method
+        if @vm.respond_to?(method_name)
+          @vm.send(method_name, *args, &block)
+        else
+          # Look up capability in PLATO
+          capability = lookup_capability(method_name)
+
+          if capability
+            execute_capability(capability, *args, &block)
+          else
+            super
+          end
+        end
+      end
+
+      # Proper introspection support
+      def respond_to_missing?(method_name, include_private = false)
+        @vm.respond_to?(method_name, include_private) ||
+          lookup_capability(method_name) ||
+          super
+      end
+
+      private
+
+      # Look up a capability by name in PLATO
+      def lookup_capability(capability_name)
+        return nil unless @plato && @vessel_id
+
+        @capabilities[capability_name] ||= @plato.query_tiles(
+          "capabilities:#{@vessel_id}",
+          capability_name.to_s
+        ).first
+      end
+
+      # Execute a capability from PLATO
+      def execute_capability(capability, *args, &block)
+        # Capability is a PLATO tile containing:
+        # - opcode: the FLUX opcode to execute
+        # - handler: Ruby code to run
+        if capability.is_a?(Hash)
+          if capability[:handler]
+            instance_exec(*args, capability[:handler], &capability[:handler])
+          elsif capability[:opcode]
+            @vm.send("op#{capability[:opcode]}", *args)
+          else
+            raise ArgumentError, 'Capability must have :handler or :opcode'
+          end
+        else
+          # Assume it's executable
+          capability.call(*args)
+        end
+      end
+    end
+  end
+end

data/lib/superinstance/flux-runtime/runtime/opcode.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../flux_vm'
+
+module Flux
+  module Runtime
+    # Runtime opcode registration module
+    # Allows Ruby code to add custom FLUX opcodes dynamically
+    class Opcode
+      class << self
+        attr_accessor :opcode_id, :format, :execute_block
+
+        # Define a new opcode at runtime
+        # @param opcode_id [Integer] 0-255 opcode number
+        # @param format [Symbol] :A, :B, :C, :D, :E, or :G
+        # @param block [Proc] execution block receiving vm and operands
+        #
+        # @example
+        #   Flux::Runtime::Opcode.define(0xF0, format: :C) do |vm, rd, ra, rb|
+        #     vm.gp[rd] = vm.gp[ra] + vm.gp[rb] * 2
+        #   end
+        def define(opcode_id, format: :C, &block)
+          @opcode_id = opcode_id
+          @format = format
+          @execute_block = block
+
+          # Register with VM
+          FluxVM.register_opcode(self)
+        end
+
+        # Execute this opcode on a VM
+        def execute(vm, *operands)
+          @execute_block.call(vm, *operands)
+        end
+
+        # Create and register in one call
+        def create(opcode_id, format: :C, &block)
+          Class.new(self) do
+            define(opcode_id, format: format, &block)
+          end
+        end
+      end
+    end
+
+    # DSL for defining opcodes
+    module OpcodeDSL
+      def define_opcode(opcode_id, format: :C, &block)
+        Opcode.define(opcode_id, format: format, &block)
+      end
+    end
+  end
+end
+
+# Convenience: include in any class to get define_opcode method
+module FluxRuntimeOpcodeDSL
+  include Flux::Runtime::OpcodeDSL
+end

data/lib/superinstance/flux-runtime/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Superinstance
+  module Flux
+    module Runtime # Intentionally empty - version defined in version.rb
+    end
+  end
+end

data/lib/superinstance-flux-runtime.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Flux
+  VERSION = '1.0.0'
+end
+
+require_relative 'superinstance/flux-runtime/version'
+require_relative 'superinstance/flux-runtime/flux_vm'
+require_relative 'superinstance/flux-runtime/opcode'
+require_relative 'superinstance/flux-runtime/assembler'
+require_relative 'superinstance/flux-runtime/disassembler'
+require_relative 'superinstance/flux-runtime/loader'
+require_relative 'superinstance/flux-runtime/exceptions'
+require_relative 'superinstance/flux-runtime/runtime/opcode'
+require_relative 'superinstance/flux-runtime/runtime/agent'
+require_relative 'superinstance/flux-runtime/cli'
+
+module Superinstance
+  module Flux
+    Runtime = Flux
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: superinstance-flux-runtime
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- SuperInstance
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: |
+  A pure Ruby implementation of the FLUX ISA v3.0 virtual machine.
+  Supports register-based execution, bytecode loading, assembly/disassembly,
+  and runtime metaprogramming for agent capabilities.
+email: engineering@superinstance.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/superinstance-flux-runtime.rb
+- lib/superinstance/flux-runtime/assembler.rb
+- lib/superinstance/flux-runtime/cli.rb
+- lib/superinstance/flux-runtime/disassembler.rb
+- lib/superinstance/flux-runtime/exceptions.rb
+- lib/superinstance/flux-runtime/flux_vm.rb
+- lib/superinstance/flux-runtime/loader.rb
+- lib/superinstance/flux-runtime/opcode.rb
+- lib/superinstance/flux-runtime/runtime/agent.rb
+- lib/superinstance/flux-runtime/runtime/opcode.rb
+- lib/superinstance/flux-runtime/version.rb
+homepage: https://github.com/SuperInstance/superinstance-flux-runtime
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.5
+signing_key: 
+specification_version: 4
+summary: Pure Ruby FLUX ISA v3.0 virtual machine with runtime metaprogramming
+test_files: []