Improve logging and queue handling in iro-runtime plugin system

Added detailed debug logs to improve traceability of plugin actions
such as registration, replugging, and deferred promises. Enhanced
queue handling with additional logging for unresolved promises.

This improves visibility into the plugin lifecycle and ensures better
debugging of runtime behaviors. No breaking changes introduced.

Author: aaronmallen

iro-runtime-rb/lib/iro/runtime/plugin/dsl.rb

@@ -19,7 +19,10 @@ def enqueue(**, &)
 
         def install
           @queue.resolve.then do |queue|
-            queue.reject(&:resolved?).each { |future| Runtime.queue.push(future) }
+            remaining = queue.reject(&:resolved?)
+            Iro.logger.debug('runtime') { "installed #{@plugin.name} with #{remaining.size} unresolved promises" }
+
+            remaining.each { |future| Runtime.queue.push(future) }
           end
         end
       end

iro-runtime-rb/lib/iro/runtime/plugin/dsl/behavior.rb

@@ -12,17 +12,25 @@ def initialize(manager, &block)
           end
 
           def enhance_module(module_name, &enhancement)
+            Iro.logger.debug('runtime') { "deferring enhancement of #{module_name}..." }
+
             on_load(module_name) do
+              Iro.logger.debug('runtime') { "#{@manager.plugin.name} enhancing #{module_name}..." }
               ModuleEnhancer.new(Runtime.constant.resolve(module_name), &enhancement)
+              Iro.logger.debug('runtime') { "#{@manager.plugin.name} enhanced #{module_name}" }
             end
           end
 
-          def on_any(event_type = :ANY, **options, &)
+          def on_any(event_type = :ANY, log: true, **options, &)
             predicate = lambda do |data|
               event_type == :ANY || (data[:type] == event_type &&
                 (options.key?(:if) ? options[:if].call(data) : true))
             end
 
+            if log
+              Iro.logger.debug('runtime') { "#{@manager.plugin.name} deferring promise pending #{event_type} event" }
+            end
+
             @manager.enqueue(if: predicate, **options.except(:if), &)
           end
 
@@ -32,7 +40,9 @@ def on_load(constant_name, **options, &)
                 (options.key?(:if) ? options[:if].call(data) : true)
             end
 
-            on_any(if: predicate, **options.except(:if), &)
+            Iro.logger.debug('runtime') { "#{@manager.plugin.name} deferring promise pending load of #{constant_name}" }
+
+            on_any(if: predicate, log: false, **options.except(:if), &)
           end
 
           def on_plugin(plugin_name, **options, &)
@@ -41,7 +51,11 @@ def on_plugin(plugin_name, **options, &)
                 (options.key?(:if) ? options[:if].call(data) : true)
             end
 
-            on_any(if: predicate, **options.except(:if), &)
+            Iro.logger.debug('runtime') do
+              "#{@manager.plugin.name} deferring promise pending plugin registration of #{plugin_name}"
+            end
+
+            on_any(if: predicate, log: false, **options.except(:if), &)
           end
 
           def on_unload(constant_name, **options, &)
@@ -50,7 +64,11 @@ def on_unload(constant_name, **options, &)
                 (options.key?(:if) ? options[:if].call(data) : true)
             end
 
-            on_any(:constant_unloaded, if: predicate, **options.except(:if), &)
+            Iro.logger.debug('runtime') do
+              "#{@manager.plugin.name} deferring promise pending unload of #{constant_name}"
+            end
+
+            on_any(:constant_unloaded, log: false, if: predicate, **options.except(:if), &)
           end
         end
       end

iro-runtime-rb/lib/iro/runtime/plugin/registry.rb

@@ -22,13 +22,17 @@ def handle_existing_plugin(name, &)
           end
 
           dsl.install
+
+          Iro.logger.debug('runtime') { "plugin #{name} repluged" }
+          Runtime.queue.resolve(type: :plugin_repluged, name:, plugin:)
+
           [name, plugin]
         end
 
         def register_new_plugin(name, root_path = nil, &)
           raise ArgumentError, '`root_path` is required for initial registration' unless root_path
 
-          Iro.logger.debug('runtime') { "registering plugin #{name}" }
+          Iro.logger.debug('runtime') { "registering plugin #{name}..." }
           plugin = Plugin.new(name:, root_path:)
 
           dsl = @mutex.synchronize do
@@ -38,6 +42,10 @@ def register_new_plugin(name, root_path = nil, &)
           end
 
           dsl.install
+
+          Iro.logger.debug('runtime') { "plugin #{name} registered" }
+          Runtime.queue.resolve(type: :plugin_registered, name:, plugin:)
+
           [name, plugin]
         end
       end