forthic 0.2.0 → 0.3.0

data/lib/forthic/grpc/client.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'grpc'
+require_relative 'forthic_runtime_services_pb'
+require_relative 'forthic_runtime_pb'
+require_relative 'serializer'
+require_relative 'errors'
+
+module Forthic
+  module Grpc
+    # gRPC client for executing words in remote Forthic runtimes
+    #
+    # Connects to remote runtimes (TypeScript, Python, other Ruby instances)
+    # and executes words with full stack serialization and error handling.
+    #
+    # Pattern: Mirrors Python client.py and TypeScript client.ts
+    #
+    # Features:
+    # - Execute individual words with stack state
+    # - Execute sequences of words (batched optimization)
+    # - List available runtime-specific modules
+    # - Get detailed module information with word metadata
+    # - Rich error handling with stack traces and context
+    #
+    # Example:
+    #   client = Forthic::Grpc::GrpcClient.new('localhost:50052')
+    #   result = client.execute_word('REVERSE', [[1, 2, 3]])
+    #   # => [[3, 2, 1]]
+    #   client.close
+    class GrpcClient
+      attr_reader :address, :stub
+
+      # Initialize the gRPC client
+      #
+      # @param address [String] Address of the remote runtime
+      #   - 'localhost:50051' for Python
+      #   - 'localhost:50052' for TypeScript
+      #   - 'localhost:50053' for Ruby
+      def initialize(address = 'localhost:50052')
+        @address = address
+
+        # Create gRPC channel (insecure for now)
+        @stub = Forthic::ForthicRuntime::Stub.new(
+          address,
+          :this_channel_is_insecure
+        )
+
+        puts "[CLIENT] Connected to Forthic runtime at #{address}"
+      end
+
+      # Execute a word in the remote runtime
+      #
+      # @param word_name [String] Name of the word to execute
+      # @param stack [Array] Current stack values
+      # @return [Array] Result stack after execution
+      # @raise [RemoteRuntimeError] If the remote runtime raises an error
+      #
+      # Example:
+      #   client.execute_word('REVERSE', [[1, 2, 3]])
+      #   # => [[3, 2, 1]]
+      def execute_word(word_name, stack)
+        puts "[EXECUTE_WORD] word='#{word_name}' stack=#{stack.inspect}"
+
+        # Serialize the stack
+        serialized_stack = stack.map { |value| Serializer.serialize_value(value) }
+
+        # Create request
+        request = Forthic::ExecuteWordRequest.new(
+          word_name: word_name,
+          stack: serialized_stack
+        )
+
+        # Execute RPC call
+        response = @stub.execute_word(request)
+
+        # Check for errors
+        if response.error && !response.error.message.empty?
+          error_info = Forthic::Grpc.parse_error_info(response.error)
+          raise RemoteRuntimeError.new(error_info)
+        end
+
+        # Deserialize result stack
+        result_stack = response.result_stack.map { |value| Serializer.deserialize_value(value) }
+
+        puts "[EXECUTE_WORD] result=#{result_stack.inspect}"
+
+        result_stack
+      rescue GRPC::BadStatus => e
+        raise "gRPC error: #{e.message}"
+      end
+
+      # Execute a sequence of words in one remote call (batched execution)
+      #
+      # @param word_names [Array<String>] Array of word names to execute in order
+      # @param stack [Array] Current stack values
+      # @return [Array] Result stack after executing all words
+      # @raise [RemoteRuntimeError] If the remote runtime raises an error
+      #
+      # Example:
+      #   client.execute_sequence(['DUP', '+'], [5])
+      #   # => [10]
+      def execute_sequence(word_names, stack)
+        puts "[EXECUTE_SEQUENCE] words=#{word_names.inspect} stack=#{stack.inspect}"
+
+        # Serialize the stack
+        serialized_stack = stack.map { |value| Serializer.serialize_value(value) }
+
+        # Create request
+        request = Forthic::ExecuteSequenceRequest.new(
+          word_names: word_names,
+          stack: serialized_stack
+        )
+
+        # Execute RPC call
+        response = @stub.execute_sequence(request)
+
+        # Check for errors
+        if response.error && !response.error.message.empty?
+          error_info = Forthic::Grpc.parse_error_info(response.error)
+          raise RemoteRuntimeError.new(error_info)
+        end
+
+        # Deserialize result stack
+        result_stack = response.result_stack.map { |value| Serializer.deserialize_value(value) }
+
+        puts "[EXECUTE_SEQUENCE] result=#{result_stack.inspect}"
+
+        result_stack
+      rescue GRPC::BadStatus => e
+        raise "gRPC error: #{e.message}"
+      end
+
+      # List available runtime-specific modules
+      #
+      # @return [Array<Hash>] Array of module summaries with:
+      #   - :name [String] Module name
+      #   - :description [String] Module description
+      #   - :word_count [Integer] Number of words in module
+      #   - :runtime_specific [Boolean] Whether module is runtime-specific
+      #
+      # Example:
+      #   client.list_modules
+      #   # => [{name: 'pandas', description: '...', word_count: 50, runtime_specific: true}]
+      def list_modules
+        puts "[LIST_MODULES] Fetching module list..."
+
+        request = Forthic::ListModulesRequest.new
+
+        # Execute RPC call
+        response = @stub.list_modules(request)
+
+        # Convert to Ruby hashes
+        modules = response.modules.map do |module_summary|
+          {
+            name: module_summary.name,
+            description: module_summary.description,
+            word_count: module_summary.word_count,
+            runtime_specific: module_summary.runtime_specific
+          }
+        end
+
+        puts "[LIST_MODULES] Found #{modules.length} modules"
+
+        modules
+      rescue GRPC::BadStatus => e
+        raise "gRPC error: #{e.message}"
+      end
+
+      # Get detailed information about a specific module
+      #
+      # @param module_name [String] Name of the module
+      # @return [Hash] Module details with:
+      #   - :name [String] Module name
+      #   - :description [String] Module description
+      #   - :words [Array<Hash>] Array of word info hashes with:
+      #     - :name [String] Word name
+      #     - :stack_effect [String] Stack effect notation
+      #     - :description [String] Word description
+      #
+      # Example:
+      #   client.get_module_info('pandas')
+      #   # => {name: 'pandas', description: '...', words: [...]}
+      def get_module_info(module_name)
+        puts "[GET_MODULE_INFO] module='#{module_name}'"
+
+        request = Forthic::GetModuleInfoRequest.new(module_name: module_name)
+
+        # Execute RPC call
+        response = @stub.get_module_info(request)
+
+        # Convert to Ruby hash
+        words = response.words.map do |word_info|
+          {
+            name: word_info.name,
+            stack_effect: word_info.stack_effect,
+            description: word_info.description
+          }
+        end
+
+        result = {
+          name: response.name,
+          description: response.description,
+          words: words
+        }
+
+        puts "[GET_MODULE_INFO] Found #{words.length} words"
+
+        result
+      rescue GRPC::BadStatus => e
+        raise "gRPC error: #{e.message}"
+      end
+
+      # Close the gRPC channel
+      #
+      # Should be called when done using the client to clean up resources
+      def close
+        puts "[CLIENT] Closing connection to #{@address}"
+        # Note: Ruby gRPC doesn't have an explicit close method for stubs
+        # The channel will be cleaned up automatically when the object is GC'd
+      end
+    end
+  end
+end

data/lib/forthic/grpc/errors.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative 'forthic_runtime_pb'
+
+module Forthic
+  module Grpc
+    # Error information from a remote runtime
+    #
+    # Preserves context, stack traces, and metadata from errors that occur
+    # in remote Forthic runtimes (TypeScript, Python, etc.)
+    class RemoteErrorInfo
+      attr_reader :message, :runtime, :stack_trace, :error_type,
+                  :word_location, :module_name, :context
+
+      def initialize(message:, runtime:, stack_trace: [], error_type: 'Error',
+                     word_location: nil, module_name: nil, context: {})
+        @message = message
+        @runtime = runtime
+        @stack_trace = stack_trace
+        @error_type = error_type
+        @word_location = word_location
+        @module_name = module_name
+        @context = context || {}
+      end
+    end
+
+    # Custom error class for errors that occur in remote runtimes
+    #
+    # Preserves stack trace and context from the remote runtime and provides
+    # rich error reporting with full context.
+    #
+    # Pattern: Mirrors Python errors.py and TypeScript errors.ts
+    class RemoteRuntimeError < StandardError
+      attr_reader :runtime, :remote_stack_trace, :error_type,
+                  :word_location, :module_name, :context, :error_info
+
+      def initialize(error_info)
+        @error_info = error_info
+        @runtime = error_info.runtime
+        @remote_stack_trace = error_info.stack_trace
+        @error_type = error_info.error_type
+        @word_location = error_info.word_location
+        @module_name = error_info.module_name
+        @context = error_info.context
+
+        # Build a rich error message
+        message = build_message
+
+        super(message)
+      end
+
+      # Build a rich error message with full context
+      #
+      # @return [String] Formatted error message
+      def build_message
+        msg = "Error in #{@runtime} runtime: #{@error_info.message}"
+
+        msg += "\n  Module: #{@module_name}" if @module_name
+        msg += "\n  Location: #{@word_location}" if @word_location
+
+        if @context && !@context.empty?
+          msg += "\n  Context:"
+          @context.each do |key, value|
+            msg += "\n    #{key}: #{value}"
+          end
+        end
+
+        msg
+      end
+
+      # Get the full stack trace including both local and remote context
+      #
+      # @return [String] Full stack trace
+      def get_full_stack_trace
+        result = "#{self.class.name}: #{message}\n"
+
+        # Add local Ruby stack
+        result += "\nLocal stack (Ruby):\n"
+        result += backtrace.join("\n") if backtrace
+
+        # Add remote stack trace
+        if @remote_stack_trace && !@remote_stack_trace.empty?
+          result += "\n\nRemote stack (#{@runtime}):\n"
+          result += @remote_stack_trace.join("\n")
+        end
+
+        result
+      end
+
+      # Get a formatted error report with all available context
+      #
+      # @return [String] Detailed error report
+      def get_error_report
+        report = "=" * 80 + "\n"
+        report += "REMOTE RUNTIME ERROR\n"
+        report += "=" * 80 + "\n\n"
+
+        report += "Runtime: #{@runtime}\n"
+        report += "Error Type: #{@error_type}\n"
+        report += "Message: #{@error_info.message}\n"
+
+        report += "Module: #{@module_name}\n" if @module_name
+        report += "Location: #{@word_location}\n" if @word_location
+
+        if @context && !@context.empty?
+          report += "\nContext:\n"
+          @context.each do |key, value|
+            report += "  #{key}: #{value}\n"
+          end
+        end
+
+        report += "\n" + "-" * 80 + "\n"
+        report += "Stack Trace:\n"
+        report += "-" * 80 + "\n"
+
+        if @remote_stack_trace && !@remote_stack_trace.empty?
+          report += @remote_stack_trace.join("\n")
+        end
+
+        report += "\n" + "=" * 80 + "\n"
+
+        report
+      end
+    end
+
+    # Parse ErrorInfo from protobuf response into RemoteErrorInfo
+    #
+    # @param error_info [Forthic::ErrorInfo] Protobuf ErrorInfo message
+    # @return [RemoteErrorInfo] Parsed error information
+    def self.parse_error_info(error_info)
+      # Handle empty strings and nil values
+      message = error_info.message.to_s.empty? ? 'Unknown error' : error_info.message
+      runtime = error_info.runtime.to_s.empty? ? 'unknown' : error_info.runtime
+      error_type = error_info.error_type.to_s.empty? ? 'Error' : error_info.error_type
+      word_location = error_info.word_location.to_s.empty? ? nil : error_info.word_location
+      module_name = error_info.module_name.to_s.empty? ? nil : error_info.module_name
+
+      RemoteErrorInfo.new(
+        message: message,
+        runtime: runtime,
+        stack_trace: error_info.stack_trace.to_a,
+        error_type: error_type,
+        word_location: word_location,
+        module_name: module_name,
+        context: error_info.context.to_h
+      )
+    end
+  end
+end

data/lib/forthic/grpc/forthic_runtime_pb.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: forthic_runtime.proto
+
+require 'google/protobuf'
+
+
+descriptor_data = "\n\x15\x66orthic_runtime.proto\x12\x07\x66orthic\"K\n\x12\x45xecuteWordRequest\x12\x11\n\tword_name\x18\x01 \x01(\t\x12\"\n\x05stack\x18\x02 \x03(\x0b\x32\x13.forthic.StackValue\"r\n\x13\x45xecuteWordResponse\x12)\n\x0cresult_stack\x18\x01 \x03(\x0b\x32\x13.forthic.StackValue\x12&\n\x05\x65rror\x18\x02 \x01(\x0b\x32\x12.forthic.ErrorInfoH\x00\x88\x01\x01\x42\x08\n\x06_error\"P\n\x16\x45xecuteSequenceRequest\x12\x12\n\nword_names\x18\x01 \x03(\t\x12\"\n\x05stack\x18\x02 \x03(\x0b\x32\x13.forthic.StackValue\"v\n\x17\x45xecuteSequenceResponse\x12)\n\x0cresult_stack\x18\x01 \x03(\x0b\x32\x13.forthic.StackValue\x12&\n\x05\x65rror\x18\x02 \x01(\x0b\x32\x12.forthic.ErrorInfoH\x00\x88\x01\x01\x42\x08\n\x06_error\"\x95\x03\n\nStackValue\x12\x13\n\tint_value\x18\x01 \x01(\x03H\x00\x12\x16\n\x0cstring_value\x18\x02 \x01(\tH\x00\x12\x14\n\nbool_value\x18\x03 \x01(\x08H\x00\x12\x15\n\x0b\x66loat_value\x18\x04 \x01(\x01H\x00\x12(\n\nnull_value\x18\x05 \x01(\x0b\x32\x12.forthic.NullValueH\x00\x12*\n\x0b\x61rray_value\x18\x06 \x01(\x0b\x32\x13.forthic.ArrayValueH\x00\x12,\n\x0crecord_value\x18\x07 \x01(\x0b\x32\x14.forthic.RecordValueH\x00\x12.\n\rinstant_value\x18\x08 \x01(\x0b\x32\x15.forthic.InstantValueH\x00\x12\x33\n\x10plain_date_value\x18\t \x01(\x0b\x32\x17.forthic.PlainDateValueH\x00\x12;\n\x14zoned_datetime_value\x18\n \x01(\x0b\x32\x1b.forthic.ZonedDateTimeValueH\x00\x42\x07\n\x05value\"\x0b\n\tNullValue\"0\n\nArrayValue\x12\"\n\x05items\x18\x01 \x03(\x0b\x32\x13.forthic.StackValue\"\x83\x01\n\x0bRecordValue\x12\x30\n\x06\x66ields\x18\x01 \x03(\x0b\x32 .forthic.RecordValue.FieldsEntry\x1a\x42\n\x0b\x46ieldsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\"\n\x05value\x18\x02 \x01(\x0b\x32\x13.forthic.StackValue:\x02\x38\x01\"\x1f\n\x0cInstantValue\x12\x0f\n\x07iso8601\x18\x01 \x01(\t\"&\n\x0ePlainDateValue\x12\x14\n\x0ciso8601_date\x18\x01 \x01(\t\"7\n\x12ZonedDateTimeValue\x12\x0f\n\x07iso8601\x18\x01 \x01(\t\x12\x10\n\x08timezone\x18\x02 \x01(\t\"\x90\x02\n\tErrorInfo\x12\x0f\n\x07message\x18\x01 \x01(\t\x12\x0f\n\x07runtime\x18\x02 \x01(\t\x12\x13\n\x0bstack_trace\x18\x03 \x03(\t\x12\x12\n\nerror_type\x18\x04 \x01(\t\x12\x1a\n\rword_location\x18\x05 \x01(\tH\x00\x88\x01\x01\x12\x18\n\x0bmodule_name\x18\x06 \x01(\tH\x01\x88\x01\x01\x12\x30\n\x07\x63ontext\x18\x07 \x03(\x0b\x32\x1f.forthic.ErrorInfo.ContextEntry\x1a.\n\x0c\x43ontextEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\x42\x10\n\x0e_word_locationB\x0e\n\x0c_module_name\"\x14\n\x12ListModulesRequest\">\n\x13ListModulesResponse\x12\'\n\x07modules\x18\x01 \x03(\x0b\x32\x16.forthic.ModuleSummary\"`\n\rModuleSummary\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x02 \x01(\t\x12\x12\n\nword_count\x18\x03 \x01(\x05\x12\x18\n\x10runtime_specific\x18\x04 \x01(\x08\"+\n\x14GetModuleInfoRequest\x12\x13\n\x0bmodule_name\x18\x01 \x01(\t\"\\\n\x15GetModuleInfoResponse\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x02 \x01(\t\x12 \n\x05words\x18\x03 \x03(\x0b\x32\x11.forthic.WordInfo\"C\n\x08WordInfo\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x14\n\x0cstack_effect\x18\x02 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x03 \x01(\t2\xca\x02\n\x0e\x46orthicRuntime\x12H\n\x0b\x45xecuteWord\x12\x1b.forthic.ExecuteWordRequest\x1a\x1c.forthic.ExecuteWordResponse\x12T\n\x0f\x45xecuteSequence\x12\x1f.forthic.ExecuteSequenceRequest\x1a .forthic.ExecuteSequenceResponse\x12H\n\x0bListModules\x12\x1b.forthic.ListModulesRequest\x1a\x1c.forthic.ListModulesResponse\x12N\n\rGetModuleInfo\x12\x1d.forthic.GetModuleInfoRequest\x1a\x1e.forthic.GetModuleInfoResponseb\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Forthic
+  ExecuteWordRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.ExecuteWordRequest").msgclass
+  ExecuteWordResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.ExecuteWordResponse").msgclass
+  ExecuteSequenceRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.ExecuteSequenceRequest").msgclass
+  ExecuteSequenceResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.ExecuteSequenceResponse").msgclass
+  StackValue = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.StackValue").msgclass
+  NullValue = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.NullValue").msgclass
+  ArrayValue = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.ArrayValue").msgclass
+  RecordValue = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.RecordValue").msgclass
+  InstantValue = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.InstantValue").msgclass
+  PlainDateValue = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.PlainDateValue").msgclass
+  ZonedDateTimeValue = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.ZonedDateTimeValue").msgclass
+  ErrorInfo = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.ErrorInfo").msgclass
+  ListModulesRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.ListModulesRequest").msgclass
+  ListModulesResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.ListModulesResponse").msgclass
+  ModuleSummary = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.ModuleSummary").msgclass
+  GetModuleInfoRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.GetModuleInfoRequest").msgclass
+  GetModuleInfoResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.GetModuleInfoResponse").msgclass
+  WordInfo = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("forthic.WordInfo").msgclass
+end

data/lib/forthic/grpc/forthic_runtime_services_pb.rb

@@ -0,0 +1,31 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# Source: forthic_runtime.proto for package 'forthic'
+
+require 'grpc'
+require_relative 'forthic_runtime_pb'
+
+module Forthic
+  module ForthicRuntime
+    # Service for executing Forthic words across runtime boundaries
+    class Service
+
+      include ::GRPC::GenericService
+
+      self.marshal_class_method = :encode
+      self.unmarshal_class_method = :decode
+      self.service_name = 'forthic.ForthicRuntime'
+
+      # Execute a single word in the remote runtime
+      rpc :ExecuteWord, ::Forthic::ExecuteWordRequest, ::Forthic::ExecuteWordResponse
+      # Execute a sequence of words in one remote call (batched execution optimization)
+      rpc :ExecuteSequence, ::Forthic::ExecuteSequenceRequest, ::Forthic::ExecuteSequenceResponse
+      # Phase 3: Module discovery
+      # List available runtime-specific modules (excludes standard library)
+      rpc :ListModules, ::Forthic::ListModulesRequest, ::Forthic::ListModulesResponse
+      # Get detailed information about a specific module
+      rpc :GetModuleInfo, ::Forthic::GetModuleInfoRequest, ::Forthic::GetModuleInfoResponse
+    end
+
+    Stub = Service.rpc_stub_class
+  end
+end

data/lib/forthic/grpc/remote_module.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative '../module'
+require_relative 'client'
+require_relative 'remote_word'
+
+module Forthic
+  module Grpc
+    # RemoteModule - Module that wraps runtime-specific words from a remote runtime
+    #
+    # This module discovers words from a remote runtime (e.g., pandas module in Python,
+    # fs module in TypeScript) and creates RemoteWord proxies for each discovered word.
+    # When used in Ruby Forthic code, these words execute in the remote runtime via gRPC.
+    #
+    # Example usage:
+    #   client = GrpcClient.new('localhost:50051')
+    #   pandas_module = RemoteModule.new('pandas', client, 'python')
+    #   pandas_module.initialize!
+    #   interp.register_module(pandas_module)
+    #   interp.use_modules(['pandas'])
+    #
+    #   # Now pandas words execute in Python runtime
+    #   interp.run('[{"name": "Alice", "age": 30}]')
+    #   interp.run('DF-FROM-RECORDS')  # Executes in Python!
+    class RemoteModule < Forthic::Module
+      attr_reader :client, :runtime_name, :initialized, :module_info
+
+      # @param module_name [String] Name of the module in the remote runtime (e.g., "pandas", "fs")
+      # @param client [GrpcClient] gRPC client connected to the remote runtime
+      # @param runtime_name [String] Name of the runtime (e.g., "python", "typescript") for debugging
+      def initialize(module_name, client, runtime_name = 'remote')
+        super(module_name)
+        @client = client
+        @runtime_name = runtime_name
+        @initialized = false
+        @module_info = nil
+      end
+
+      # Initialize the module by discovering words from the remote runtime
+      #
+      # This must be called before the module is registered with an interpreter.
+      # It fetches the module metadata and creates RemoteWord proxies for each word.
+      #
+      # @raise [StandardError] If the module cannot be initialized
+      def initialize!
+        return if @initialized
+
+        # Discover module info from remote runtime
+        @module_info = @client.get_module_info(@name)
+
+        # Create RemoteWord for each discovered word
+        words = @module_info[:words] || @module_info.words
+        words.each do |word_info|
+          # Handle both hash and object access
+          word_name = word_info[:name] || word_info.name
+          stack_effect = word_info[:stack_effect] || word_info.stack_effect
+          description = word_info[:description] || word_info.description
+
+          remote_word = RemoteWord.new(
+            word_name,
+            @client,
+            @runtime_name,
+            @name,
+            stack_effect,
+            description
+          )
+
+          # Add as exportable word (visible when module is imported)
+          add_exportable_word(remote_word)
+        end
+
+        @initialized = true
+      rescue StandardError => e
+        raise "Failed to initialize remote module '#{@name}' from #{@runtime_name} runtime: #{e.message}"
+      end
+
+      # Override set_interp to ensure module is initialized
+      #
+      # @param interp [Interpreter] The Forthic interpreter
+      # @raise [StandardError] If module is not initialized
+      def set_interp(interp)
+        unless @initialized
+          raise "RemoteModule '#{@name}' must be initialized before being registered with an interpreter. " \
+                "Call module.initialize! first."
+        end
+        super(interp)
+      end
+
+      # Get the module metadata from the remote runtime
+      #
+      # @return [GetModuleInfoResponse, nil] Module info or nil if not initialized
+      def get_module_info
+        @module_info
+      end
+
+      # Get runtime name for debugging
+      #
+      # @return [String] Runtime name
+      def get_runtime_name
+        @runtime_name
+      end
+
+      # Check if module is initialized
+      #
+      # @return [Boolean] true if initialized, false otherwise
+      def initialized?
+        @initialized
+      end
+
+      # Get count of discovered words
+      #
+      # @return [Integer] Number of words in the module
+      def word_count
+        return 0 unless @module_info
+        words = @module_info[:words] || @module_info.words
+        words ? words.length : 0
+      end
+    end
+  end
+end