ruby-mana 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04d7095024d30500930422b72e86fcdb1a27b1fa9a9f62ca70c9c124c2ceab77
-  data.tar.gz: 6e264f8292e908d45776481aa6af33bed5eb7d9113874d13e72f3a3cde513107
+  metadata.gz: 4880a32558b5c8a6d08e18d32893e3ab8ae4f9e00ba97009b7c95525998a28a2
+  data.tar.gz: 1244df8f3307dd271471f5a67d2b4b5439086ae78b63f44e1a0e1ecaecf12a40
 SHA512:
-  metadata.gz: 470e54537747878bbe07c6825a12bf515a2909af872ee4908e0eb07a0e58b31187dacadb6b20d988782a8f9a2bfaf12c4523ae09c149dc764ad90c2b8a420871
-  data.tar.gz: 1c322b45e74e8fa67aab109c10a5a7cac2d6546d1de61912157192e9f15330b8c2520bd5e90b4c70b942d36b7de4ecabfc165c2774be4b8489936e68e14614a0
+  metadata.gz: c58a40c28a7adecf324099f056a06ca65710f4ba82f9b035fed5a886be061da9cf70259b8372063cdaf60505febe8253455e874b502312811652dedd013b042c
+  data.tar.gz: 2c2c8887ef9da0f01ec7afc51c432f06fe9684e7b732659b3ae3994976d450fcffbaf0bcdb69344045f578126ee4127ebff891ec0b02d6a17ed9f29e3812a18c

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.1] - 2026-02-24
+
+### Changed
+- **Engine capability refactor** — replaced three redundant capability flags (`supports_remote_ref?`, `supports_bidirectional?`, `supports_state?`) with a single `execution_engine?` method
+- Clearer semantics: execution engines (Ruby/JS/Python) vs reasoning engines (LLM)
+- Fully backward compatible — old methods still work as derived properties
+
 ## [0.5.0] - 2026-02-22
 
 ### Added

data/data/lang-rules.yml

@@ -77,7 +77,7 @@ languages:
       - "if "
       - "is not"
       - "not in"
-      - "pass"
+      - "pass "
     anti:
       - "import this"
       - "import that"
@@ -140,8 +140,8 @@ languages:
       - "lambda {"
       - "-> {"
     weak:
-      - "end"
-      - "begin"
+      - "end "
+      - "begin "
       - "class "
       - "return "
       - "if "

data/lib/mana/engines/base.rb

@@ -10,6 +10,34 @@ module Mana
         @config = config
       end
 
+      # --- Capability queries ---
+      # Subclasses override to declare what they support.
+
+      # Is this an execution engine (Ruby/JS/Python) or a reasoning engine (LLM)?
+      # Execution engines can execute code, hold state, and be called bidirectionally.
+      # Reasoning engines process natural language but cannot hold references or state.
+      def execution_engine?
+        true
+      end
+
+      # Can this engine hold remote references to objects in other engines?
+      # Derived from execution_engine? — only execution engines support remote refs.
+      def supports_remote_ref?
+        execution_engine?
+      end
+
+      # Can code in this engine call back into another engine (bidirectional)?
+      # Derived from execution_engine? — only execution engines support bidirectional calls.
+      def supports_bidirectional?
+        execution_engine?
+      end
+
+      # Does this engine maintain mutable state across calls?
+      # Derived from execution_engine? — only execution engines maintain state.
+      def supports_state?
+        execution_engine?
+      end
+
       # Execute code/prompt in this engine, return the result
       # Subclasses must implement this
       def execute(code)

data/lib/mana/engines/javascript.rb

@@ -7,10 +7,56 @@ rescue LoadError
 end
 
 require "json"
+require "set"
 
 module Mana
   module Engines
     class JavaScript < Base
+      # JS helper code that creates Proxy wrappers for remote Ruby objects.
+      # Injected once per V8 context.
+      JS_PROXY_HELPER = <<~JS
+        (function() {
+          if (typeof __mana_create_proxy !== 'undefined') return;
+
+          // FinalizationRegistry for automatic GC of remote refs.
+          // When a JS proxy is garbage collected, notify Ruby to release the original object.
+          if (typeof FinalizationRegistry !== 'undefined') {
+            globalThis.__mana_ref_gc = new FinalizationRegistry(function(refId) {
+              try { ruby.__ref_release(refId); } catch(e) {}
+            });
+          }
+
+          globalThis.__mana_create_proxy = function(refId, typeName) {
+            var proxy = new Proxy({ __mana_ref: refId, __mana_type: typeName }, {
+              get: function(target, prop) {
+                if (prop === '__mana_ref') return target.__mana_ref;
+                if (prop === '__mana_type') return target.__mana_type;
+                if (prop === '__mana_alive') return ruby.__ref_alive(refId);
+                if (prop === 'release') return function() { ruby.__ref_release(refId); };
+                if (prop === 'toString' || prop === Symbol.toPrimitive) {
+                  return function() { return ruby.__ref_to_s(refId); };
+                }
+                if (prop === 'inspect') {
+                  return function() { return 'RemoteRef<' + typeName + '#' + refId + '>'; };
+                }
+                if (typeof prop === 'symbol') return undefined;
+                return function() {
+                  var args = Array.prototype.slice.call(arguments);
+                  return ruby.__ref_call(refId, prop, JSON.stringify(args));
+                };
+              }
+            });
+
+            // Register with FinalizationRegistry so GC triggers release
+            if (globalThis.__mana_ref_gc) {
+              globalThis.__mana_ref_gc.register(proxy, refId);
+            }
+
+            return proxy;
+          };
+        })();
+      JS
+
       # Thread-local persistent V8 context (lazy-loaded, long-running)
       def self.context
         Thread.current[:mana_js_context] ||= create_context
@@ -21,21 +67,26 @@ module Mana
       end
 
       def self.reset!
-        Thread.current[:mana_js_context]&.dispose
+        ctx = Thread.current[:mana_js_context]
+        ctx&.dispose
         Thread.current[:mana_js_context] = nil
+        Thread.current[:mana_js_callbacks_attached] = nil
+        ObjectRegistry.reset!
       end
 
       def execute(code)
         ctx = self.class.context
 
-        # 1. Scan code for Ruby variable references
-        #    Variables from Ruby binding are injected into JS context
+        # 1. Attach Ruby callbacks (methods + effects + ref operations)
+        attach_ruby_callbacks(ctx)
+
+        # 2. Inject Ruby variables into JS scope
         inject_ruby_vars(ctx, code)
 
-        # 2. Execute the JS code
+        # 3. Execute the JS code
         result = ctx.eval(code)
 
-        # 3. Extract any new/modified variables back to Ruby binding
+        # 4. Extract any new/modified variables back to Ruby binding
         extract_js_vars(ctx, code)
 
         result
@@ -43,20 +94,183 @@ module Mana
 
       private
 
+      def attach_ruby_callbacks(ctx)
+        attached = Thread.current[:mana_js_callbacks_attached] ||= Set.new
+
+        # Install the JS Proxy helper (once per context)
+        unless attached.include?("__proxy_helper")
+          ctx.eval(JS_PROXY_HELPER)
+          attached << "__proxy_helper"
+        end
+
+        # ruby.read / ruby.write -- variable bridge
+        unless attached.include?("ruby.read")
+          bnd = @binding
+          ctx.attach("ruby.read", proc { |name|
+            sym = name.to_sym
+            if bnd.local_variables.include?(sym)
+              val = bnd.local_variable_get(sym)
+              json_safe(val)
+            else
+              nil
+            end
+          })
+          attached << "ruby.read"
+        end
+
+        unless attached.include?("ruby.write")
+          bnd = @binding
+          ctx.attach("ruby.write", proc { |name, value|
+            bnd.local_variable_set(name.to_sym, value)
+            value
+          })
+          attached << "ruby.write"
+        end
+
+        # Remote reference operations
+        attach_ref_callbacks(ctx, attached)
+
+        # Attach methods from the caller's receiver
+        attach_receiver_methods(ctx, attached)
+
+        # Attach registered Mana effects
+        attach_effects(ctx, attached)
+      end
+
+      # Attach callbacks for operating on remote Ruby object references from JS.
+      def attach_ref_callbacks(ctx, attached)
+        registry = ObjectRegistry.current
+
+        unless attached.include?("ruby.__ref_call")
+          ctx.attach("ruby.__ref_call", proc { |ref_id, method_name, args_json|
+            obj = registry.get(ref_id)
+            raise "Remote reference #{ref_id} has been released" unless obj
+
+            args = args_json ? JSON.parse(args_json) : []
+            result = obj.public_send(method_name.to_sym, *args)
+            json_safe(result)
+          })
+          attached << "ruby.__ref_call"
+        end
+
+        unless attached.include?("ruby.__ref_release")
+          ctx.attach("ruby.__ref_release", proc { |ref_id|
+            registry.release(ref_id)
+            nil
+          })
+          attached << "ruby.__ref_release"
+        end
+
+        unless attached.include?("ruby.__ref_alive")
+          ctx.attach("ruby.__ref_alive", proc { |ref_id|
+            registry.registered?(ref_id)
+          })
+          attached << "ruby.__ref_alive"
+        end
+
+        unless attached.include?("ruby.__ref_to_s")
+          ctx.attach("ruby.__ref_to_s", proc { |ref_id|
+            obj = registry.get(ref_id)
+            obj ? obj.to_s : "released"
+          })
+          attached << "ruby.__ref_to_s"
+        end
+      end
+
+      def attach_receiver_methods(ctx, attached)
+        receiver = @binding.receiver
+        user_methods = receiver.class.instance_methods(false) -
+                       Object.instance_methods -
+                       [:~@]
+
+        user_methods.each do |method_name|
+          key = "ruby.#{method_name}"
+          next if attached.include?(key)
+
+          recv = receiver
+          ctx.attach(key, proc { |*args| json_safe(recv.public_send(method_name, *args)) })
+          attached << key
+        end
+      end
+
+      def attach_effects(ctx, attached)
+        Mana::EffectRegistry.registry.each do |name, effect|
+          key = "ruby.#{name}"
+          next if attached.include?(key)
+
+          eff = effect
+          ctx.attach(key, proc { |*args|
+            input = if args.length == 1 && args[0].is_a?(Hash)
+                      args[0]
+                    elsif eff.params.length == args.length
+                      eff.params.zip(args).to_h { |p, v| [p[:name], v] }
+                    else
+                      {}
+                    end
+            json_safe(eff.call(input))
+          })
+          attached << key
+        end
+      end
+
       def inject_ruby_vars(ctx, code)
         @binding.local_variables.each do |var_name|
-          # Only inject variables actually referenced in the code (word-boundary match)
-          pattern = /\b#{Regexp.escape(var_name.to_s)}\b/
-          next unless code.match?(pattern)
+          next unless code.match?(/\b#{Regexp.escape(var_name.to_s)}\b/)
 
           value = @binding.local_variable_get(var_name)
-          serialized = serialize(value)
-          ctx.eval("var #{var_name} = #{JSON.generate(serialized)}")
+          inject_value(ctx, var_name.to_s, value)
         rescue => e
           next
         end
       end
 
+      # Inject a single value into the JS context.
+      # Simple types are serialized to JSON. Complex objects become remote ref proxies.
+      def inject_value(ctx, name, value)
+        case value
+        when Numeric, String, TrueClass, FalseClass, NilClass
+          ctx.eval("var #{name} = #{JSON.generate(value)}")
+        when Symbol
+          ctx.eval("var #{name} = #{JSON.generate(value.to_s)}")
+        when Array
+          ctx.eval("var #{name} = #{JSON.generate(serialize_array(value))}")
+        when Hash
+          ctx.eval("var #{name} = #{JSON.generate(serialize_hash(value))}")
+        else
+          # Complex object → register and create JS Proxy
+          ref_id = ObjectRegistry.current.register(value)
+          ctx.eval("var #{name} = __mana_create_proxy(#{ref_id}, #{JSON.generate(value.class.name)})")
+        end
+      end
+
+      def serialize_array(arr)
+        arr.map { |v| simple_value?(v) ? serialize_simple(v) : v.to_s }
+      end
+
+      def serialize_hash(hash)
+        hash.transform_keys(&:to_s).transform_values { |v|
+          simple_value?(v) ? serialize_simple(v) : v.to_s
+        }
+      end
+
+      def simple_value?(value)
+        case value
+        when Numeric, String, Symbol, TrueClass, FalseClass, NilClass, Array, Hash
+          true
+        else
+          false
+        end
+      end
+
+      def serialize_simple(value)
+        case value
+        when Symbol then value.to_s
+        when Array then serialize_array(value)
+        when Hash then serialize_hash(value)
+        else value
+        end
+      end
+
       def extract_js_vars(ctx, code)
         declared_vars = extract_declared_vars(code)
         declared_vars.each do |var_name|
@@ -72,19 +286,29 @@ module Mana
 
       def extract_declared_vars(code)
         vars = []
-        # Match: const x = ..., let x = ..., var x = ...
         code.scan(/\b(?:const|let|var)\s+(\w+)\s*=/).each { |m| vars << m[0] }
-        # Match: bare assignment at start of line: x = ...
-        # But NOT: x === ..., x == ..., x => ...
         code.scan(/^(\w+)\s*=[^=>]/).each { |m| vars << m[0] }
         vars.uniq
       end
 
       def deserialize(value)
-        # JS values come back as Ruby primitives from mini_racer
-        # Arrays and Hashes are automatically converted
         value
       end
+
+      def json_safe(value)
+        case value
+        when Numeric, String, TrueClass, FalseClass, NilClass
+          value
+        when Symbol
+          value.to_s
+        when Array
+          value.map { |v| json_safe(v) }
+        when Hash
+          value.transform_keys(&:to_s).transform_values { |v| json_safe(v) }
+        else
+          value.to_s
+        end
+      end
     end
   end
 end

data/lib/mana/engines/llm.rb

@@ -5,6 +5,14 @@ require "json"
 module Mana
   module Engines
     class LLM < Base
+      # LLM is a reasoning engine, not an execution engine.
+      # It understands natural language and uses tool-calling to interact with
+      # Ruby variables, but it cannot hold remote object references, maintain
+      # state, or be called back from other engines.
+      def execution_engine?
+        false
+      end
+
       TOOLS = [
         {
           name: "read_var",

data/lib/mana/engines/python.rb

@@ -11,6 +11,50 @@ require "json"
 module Mana
   module Engines
     class Python < Base
+      # Python helper code injected once per namespace.
+      # Sets up weak-ref tracking so when Python drops a reference to a
+      # complex Ruby object, the ObjectRegistry is notified.
+      PY_GC_HELPER = <<~PYTHON
+        import weakref as _mana_wr
+        import builtins as _mana_bi
+        _mana_bi._mana_weakref = _mana_wr
+
+        class __ManaRef:
+            """Weak-ref release notifier for Ruby objects passed to Python."""
+            _release_fn = None
+            _instances = {}
+
+            @classmethod
+            def set_release_fn(cls, fn):
+                cls._release_fn = fn
+
+            @classmethod
+            def track(cls, ref_id, obj):
+                """Track a Ruby object. When Python GC collects it, notify Ruby."""
+                import builtins
+                _wr = builtins._mana_weakref
+                try:
+                    ref = _wr.ref(obj, lambda r, rid=ref_id: cls._release(rid))
+                    cls._instances[ref_id] = ref
+                except TypeError:
+                    # Some objects can't be weakly referenced; skip them
+                    pass
+
+            @classmethod
+            def _release(cls, ref_id):
+                cls._instances.pop(ref_id, None)
+                if cls._release_fn:
+                    try:
+                        cls._release_fn(ref_id)
+                    except Exception:
+                        pass
+
+            @classmethod
+            def release_all(cls):
+                for ref_id in list(cls._instances.keys()):
+                    cls._release(ref_id)
+      PYTHON
+
       # Thread-local persistent Python state
       # PyCall shares a single Python interpreter per process,
       # but we track our own variable namespace
@@ -25,14 +69,25 @@ module Mana
       def self.reset!
         ns = Thread.current[:mana_py_namespace]
         if ns
+          begin
+            mana_ref = ns["__ManaRef"]
+            mana_ref.release_all if mana_ref
+          rescue => e
+            # ignore
+          end
           PyCall.exec("pass") # ensure interpreter is alive
           Thread.current[:mana_py_namespace] = nil
         end
+        Thread.current[:mana_py_gc_injected] = nil
+        ObjectRegistry.reset!
       end
 
       def execute(code)
         ns = self.class.namespace
 
+        # 0. Inject GC helper (once per namespace)
+        inject_gc_helper(ns)
+
         # 1. Inject Ruby variables into Python namespace
         inject_ruby_vars(ns, code)
 
@@ -59,6 +114,21 @@ module Mana
 
       private
 
+      def inject_gc_helper(ns)
+        return if Thread.current[:mana_py_gc_injected]
+
+        PyCall.exec(PY_GC_HELPER, locals: ns)
+
+        # Wire up the release callback: when Python GC collects a tracked object,
+        # __ManaRef calls this proc to release it from the Ruby ObjectRegistry.
+        registry = ObjectRegistry.current
+        release_fn = proc { |ref_id| registry.release(ref_id.to_i) }
+        mana_ref = ns["__ManaRef"]
+        mana_ref.set_release_fn(release_fn)
+
+        Thread.current[:mana_py_gc_injected] = true
+      end
+
       def inject_ruby_vars(ns, code)
         @binding.local_variables.each do |var_name|
           value = @binding.local_variable_get(var_name)
@@ -112,8 +182,9 @@ module Mana
       end
 
       # Serialize Ruby values for Python injection.
-      # Procs/lambdas and Ruby objects are passed directly --
-      # PyCall wraps them so Python can call their methods.
+      # Simple types are copied. Complex objects are passed directly via PyCall
+      # (which wraps them so Python can call their methods) AND registered in
+      # the ObjectRegistry for lifecycle tracking + GC notification.
       def serialize_for_py(value)
         case value
         when Numeric, String, TrueClass, FalseClass, NilClass
@@ -128,14 +199,27 @@ module Mana
             h[key] = serialize_for_py(v)
           end
         when Proc, Method
-          # Pass callables directly -- PyCall wraps them as Python callables
+          ref_id = ObjectRegistry.current.register(value)
+          track_in_python(ref_id, value)
           value
         else
-          # Pass Ruby objects directly -- Python can call their methods via PyCall
+          ref_id = ObjectRegistry.current.register(value)
+          track_in_python(ref_id, value)
           value
         end
       end
 
+      # Tell the Python __ManaRef tracker to watch this object via weakref.
+      def track_in_python(ref_id, value)
+        ns = self.class.namespace
+        begin
+          mana_ref = ns["__ManaRef"]
+          mana_ref.track(ref_id, value) if mana_ref
+        rescue => e
+          # Non-fatal: some objects can't be weakly referenced in Python
+        end
+      end
+
       def deserialize_py(value)
         if defined?(PyCall::PyObjectWrapper) && value.is_a?(PyCall::PyObjectWrapper)
           begin
@@ -202,7 +286,7 @@ module Mana
           return val.call(*args) if val.respond_to?(:call)
         end
 
-        # Then try the receiver (public methods only)
+        # Then try the receiver
         if @receiver.respond_to?(name_s)
           return @receiver.public_send(name_s, *args)
         end
@@ -220,7 +304,7 @@ module Mana
           return true if val.respond_to?(:call)
         end
 
-        # Check receiver (public methods only, matching method_missing)
+        # Check receiver (public methods only)
         return true if @receiver.respond_to?(name_s)
 
         super

data/lib/mana/object_registry.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Mana
+  # Thread-local registry for cross-engine object references.
+  #
+  # When a complex Ruby object is passed to JS/Python, it gets registered here
+  # with a unique integer ID. The foreign engine holds a proxy with that ID and
+  # routes method calls back through the bidirectional channel.
+  #
+  # Thread-local so each engine context (which is also thread-local) has its own
+  # isolated set of references.
+  class ObjectRegistry
+    attr_reader :objects
+
+    def initialize
+      @objects = {}
+      @next_id = 1
+      @release_callbacks = []
+    end
+
+    # Store an object and return its reference ID.
+    # If the same object is already registered, return the existing ID.
+    def register(obj)
+      # Check if already registered (by object_id for identity, not equality)
+      @objects.each do |id, entry|
+        return id if entry[:object].equal?(obj)
+      end
+
+      id = @next_id
+      @next_id += 1
+      @objects[id] = { object: obj, type: obj.class.name }
+      id
+    end
+
+    # Retrieve an object by its reference ID.
+    def get(id)
+      entry = @objects[id]
+      entry ? entry[:object] : nil
+    end
+
+    # Register a callback invoked when any reference is released.
+    # The callback receives (id, entry) where entry is { object:, type: }.
+    def on_release(&block)
+      @release_callbacks << block
+    end
+
+    # Release a reference. Returns true if it existed.
+    # Fires registered on_release callbacks with the id and entry.
+    def release(id)
+      entry = @objects.delete(id)
+      return false unless entry
+
+      @release_callbacks.each do |cb|
+        cb.call(id, entry)
+      rescue => e
+        # Don't let callback errors break the release
+      end
+      true
+    end
+
+    # Number of live references.
+    def size
+      @objects.size
+    end
+
+    # Remove all references. Fires on_release for each.
+    def clear!
+      ids = @objects.keys.dup
+      ids.each { |id| release(id) }
+      @next_id = 1
+    end
+
+    # Check if an ID is registered.
+    def registered?(id)
+      @objects.key?(id)
+    end
+
+    # Thread-local singleton access
+    def self.current
+      Thread.current[:mana_object_registry] ||= new
+    end
+
+    def self.reset!
+      registry = Thread.current[:mana_object_registry]
+      registry&.clear!
+      Thread.current[:mana_object_registry] = nil
+    end
+  end
+end

data/lib/mana/remote_ref.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Mana
+  # A proxy object representing a remote reference to an object in another engine.
+  #
+  # When JS or Python receives a complex Ruby object, they get a RemoteRef handle.
+  # Method calls on the proxy are routed back to the original object via the
+  # ObjectRegistry and the bidirectional calling channel.
+  #
+  # On the Ruby side, RemoteRef can also wrap foreign objects (JS/Python) that
+  # were passed to Ruby — method calls go through the engine's eval mechanism.
+  #
+  # GC behavior:
+  # - When a RemoteRef is garbage collected, its finalizer releases the entry
+  #   from the ObjectRegistry.
+  # - If an `on_release` callback is registered on the registry, it fires,
+  #   allowing the source engine to be notified (e.g., to free the foreign object).
+  class RemoteRef
+    attr_reader :ref_id, :source_engine, :type_name
+
+    def initialize(ref_id, source_engine:, type_name: nil, registry: nil)
+      @ref_id = ref_id
+      @source_engine = source_engine
+      @type_name = type_name
+      @registry = registry || ObjectRegistry.current
+      setup_release_callback
+    end
+
+    # Call a method on the remote object
+    def method_missing(name, *args, &block)
+      name_s = name.to_s
+
+      # Don't proxy Ruby internal methods
+      return super if %w[__id__ __send__ class is_a? kind_of? instance_of? respond_to? respond_to_missing? equal? nil? frozen? inspect to_s hash].include?(name_s)
+
+      obj = @registry.get(@ref_id)
+      raise Mana::Error, "Remote reference #{@ref_id} has been released" unless obj
+
+      obj.public_send(name, *args, &block)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      obj = @registry.get(@ref_id)
+      return false unless obj
+      obj.respond_to?(name, false)
+    end
+
+    # Explicitly release this reference
+    def release!
+      @registry.release(@ref_id)
+    end
+
+    # Check if the referenced object is still alive
+    def alive?
+      @registry.registered?(@ref_id)
+    end
+
+    def inspect
+      "#<Mana::RemoteRef id=#{@ref_id} engine=#{@source_engine} type=#{@type_name}>"
+    end
+
+    def to_s
+      obj = @registry.get(@ref_id)
+      obj ? obj.to_s : inspect
+    end
+
+    private
+
+    # Set up a release callback via Ruby finalizer.
+    # When this RemoteRef is garbage collected, the registry entry is released,
+    # which in turn fires any on_release callbacks (notifying the source engine).
+    # Uses a class method to avoid capturing `self` in the closure.
+    def setup_release_callback
+      release_proc = self.class.send(:release_callback, @ref_id, @registry)
+      ObjectSpace.define_finalizer(self, release_proc)
+    end
+
+    # Build a release proc that doesn't reference the RemoteRef instance.
+    # This avoids the "finalizer references object to be finalized" warning.
+    def self.release_callback(ref_id, registry)
+      proc { |_| registry.release(ref_id) }
+    end
+    private_class_method :release_callback
+  end
+end

data/lib/mana/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mana
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

data/lib/mana.rb

@@ -11,6 +11,8 @@ require_relative "mana/namespace"
 require_relative "mana/memory_store"
 require_relative "mana/context_window"
 require_relative "mana/memory"
+require_relative "mana/object_registry"
+require_relative "mana/remote_ref"
 require_relative "mana/engines/base"
 require_relative "mana/engines/llm"
 require_relative "mana/engines/ruby_eval"
@@ -49,6 +51,7 @@ module Mana
       @config = Config.new
       EffectRegistry.clear!
       Engines.reset_detector!
+      ObjectRegistry.reset!
       Engines::JavaScript.reset! if defined?(Engines::JavaScript)
       Engines::Python.reset! if defined?(Engines::Python)
       Thread.current[:mana_memory] = nil

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mana
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Carl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-22 00:00:00.000000000 Z
+date: 2026-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binding_of_caller
@@ -73,6 +73,8 @@ files:
 - lib/mana/mixin.rb
 - lib/mana/mock.rb
 - lib/mana/namespace.rb
+- lib/mana/object_registry.rb
+- lib/mana/remote_ref.rb
 - lib/mana/string_ext.rb
 - lib/mana/test.rb
 - lib/mana/version.rb