lex-llm 0.5.4 → 0.6.2

data/lib/legion/extensions/llm/provider.rb

@@ -10,6 +10,10 @@ module Legion
           @data = hash.transform_keys(&:to_sym)
         end
 
+        def to_h
+          @data.dup
+        end
+
         def respond_to_missing?(name, include_private = false)
           @data.key?(name.to_sym) || super
         end
@@ -31,6 +35,46 @@ module Legion
         include Legion::Cache::Helper
 
         MODEL_DETAIL_CACHE_SCHEMA_VERSION = 2
+        CAPABILITY_CONFIG_KEYS = %i[
+          capabilities
+          enable_completion
+          enable_embedding
+          enable_embeddings
+          enable_streaming
+          enable_tools
+          enable_functions
+          enable_function_calling
+          enable_thinking
+          enable_reasoning
+          enable_vision
+          enable_structured_output
+          enable_moderation
+          enable_image
+          enable_images
+          enable_image_generation
+          enable_audio_transcription
+          enable_audio_speech
+          enable_audio_generation
+          completion_flag
+          embedding_flag
+          embeddings_flag
+          streaming_flag
+          tool_flag
+          tools_flag
+          functions_flag
+          function_calling_flag
+          thinking_flag
+          reasoning_flag
+          vision_flag
+          structured_output_flag
+          moderation_flag
+          image_flag
+          images_flag
+          image_generation_flag
+          audio_transcription_flag
+          audio_speech_flag
+          audio_generation_flag
+        ].freeze
 
         attr_reader :config, :connection
 
@@ -145,11 +189,14 @@ module Legion
 
           provider_health = health(live:)
           @cached_offerings = Array(list_models(live:, **filters)).filter_map do |model|
+            publish_discovered_model_to_registry(model, provider_health:, live:)
             next unless model_matches_filters?(model, filters)
             next unless model_allowed?(model.id)
 
+            log.debug("[#{slug}] instance=#{provider_instance_id} action=model_discovered model=#{model.id} family=#{model.family}")
             offering_from_model(model, health: provider_health)
           end
+          log.info("[#{slug}] instance=#{provider_instance_id} action=discover_complete model_count=#{Array(@cached_offerings).size}")
           @cached_offerings
         rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
           log.warn("[#{slug}] instance=#{provider_instance_id} unreachable: #{e.message}")
@@ -158,17 +205,45 @@ module Legion
           []
         end
 
+        def publish_discovered_model_to_registry(model, provider_health:, live:)
+          publisher = discovery_registry_publisher
+          return unless publisher.respond_to?(:publish_models_async)
+
+          publisher.publish_models_async([model], readiness: discovery_registry_readiness(provider_health, live:))
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.publish_discovered_model')
+        end
+
+        def discovery_registry_publisher
+          return unless self.class.respond_to?(:registry_publisher)
+
+          self.class.registry_publisher
+        rescue StandardError
+          nil
+        end
+
+        def discovery_registry_readiness(provider_health, live:)
+          {
+            provider: slug.to_sym,
+            configured: configured?,
+            ready: provider_health[:ready] == true,
+            live: live,
+            health: provider_health
+          }
+        end
+
         def health(live: false)
           readiness_data = readiness(live:)
           raw_health = readiness_data[:health] || readiness_data['health'] || {}
           status = health_status(readiness_data, raw_health)
+          latency_ms = (raw_health[:latency_ms] || raw_health['latency_ms'] if raw_health.is_a?(Hash))
           {
             provider: slug.to_sym,
             instance_id: provider_instance_id,
             status:,
             ready: readiness_data[:ready] == true || readiness_data['ready'] == true,
             circuit_state: status == 'healthy' ? 'closed' : 'open',
-            latency_ms: raw_health[:latency_ms] || raw_health['latency_ms'],
+            latency_ms: latency_ms,
             raw: raw_health
           }.compact
         rescue StandardError => e
@@ -338,20 +413,44 @@ module Legion
 
         # ── Model allow-list / deny-list filtering ────────────────────────
 
+        # Resolve model_whitelist with specificity cascade:
+        # 1. Instance-level  (config.model_whitelist — extensions.llm.<provider>.instances.<id>.model_whitelist)
+        # 2. Provider-level  (extensions.llm.<provider>.model_whitelist)
+        # 3. Global          (extensions.llm.model_whitelist)
+        # Returns the first non-nil, non-empty value found.
         def model_whitelist
           wl = config.model_whitelist if config.respond_to?(:model_whitelist)
-          wl ||= settings[:model_whitelist] if respond_to?(:settings) && settings.is_a?(Hash)
+          wl ||= instance_setting(:model_whitelist)
           wl ||= runtime_provider_setting(:model_whitelist)
+          wl ||= global_llm_setting(:model_whitelist)
           Array(wl).map { |p| p.to_s.downcase }
         end
 
+        # Resolve model_blacklist with the same specificity cascade as model_whitelist.
         def model_blacklist
           bl = config.model_blacklist if config.respond_to?(:model_blacklist)
-          bl ||= settings[:model_blacklist] if respond_to?(:settings) && settings.is_a?(Hash)
+          bl ||= instance_setting(:model_blacklist)
           bl ||= runtime_provider_setting(:model_blacklist)
+          bl ||= global_llm_setting(:model_blacklist)
           Array(bl).map { |p| p.to_s.downcase }
         end
 
+        # Pull a setting from the instance-level settings hash (if available),
+        # distinct from the config object which is a HashConfig wrapper.
+        def instance_setting(key)
+          config_hash =
+            if instance_variable_defined?(:@settings)
+              @settings
+            elsif respond_to?(:settings)
+              settings
+            else
+              config
+            end
+          config_hash = config_hash.to_h if config_hash.respond_to?(:to_h)
+          config_hash.is_a?(Hash) ? (config_hash[key] || config_hash[key.to_s]) : nil
+        end
+
+        # Provider-level setting: extensions.llm.<provider>.<key>
         def runtime_provider_setting(key)
           return nil unless defined?(Legion::Settings)
 
@@ -367,8 +466,35 @@ module Legion
           nil
         end
 
+        # Global LLM setting: extensions.llm.<key> (lowest specificity)
+        def global_llm_setting(key)
+          return nil unless defined?(Legion::Settings)
+
+          llm_conf = Legion::Settings.dig(:extensions, :llm)
+          llm_conf.is_a?(Hash) ? llm_conf[key] : nil
+        rescue StandardError
+          nil
+        end
+
         def model_allowed?(model_name)
-          self.class.policy_allows?(model_name, whitelist: model_whitelist, blacklist: model_blacklist)
+          wl = model_whitelist
+          bl = model_blacklist
+          allowed = self.class.policy_allows?(model_name, whitelist: wl, blacklist: bl)
+
+          unless allowed
+            reason_parts = []
+            reason_parts << 'whitelist' if wl.any?
+            reason_parts << 'blacklist' if bl.any?
+            reason_str = reason_parts.empty? ? 'policy' : reason_parts.join(',')
+            policy_src = if wl.any?
+                           "wl=[#{wl.first(5).join(',')}#{',...' if wl.size > 5}]"
+                         else
+                           'no-whitelist'
+                         end
+            log.debug("[#{self.class.slug}] action=model_rejected name=#{model_name} reason=#{reason_str} #{policy_src}")
+          end
+
+          allowed
         end
 
         # Single source of truth for model-policy matching, usable both at runtime
@@ -388,19 +514,38 @@ module Legion
           true
         end
 
-        # Effective whitelist/blacklist for an instance config: per-instance config
-        # first, then the provider-level setting (mirrors instance #model_whitelist
-        # resolution order). Used by provider extensions when picking a default_model.
+        # Effective whitelist/blacklist for an instance config at build time
+        # (before provider instance exists). Same specificity cascade:
+        # 1. Per-instance  (config hash — extensions.llm.<provider>.instances.<id>.model_whitelist)
+        # 2. Provider-level (extensions.llm.<provider>.model_whitelist)
+        # 3. Global        (extensions.llm.model_whitelist)
         def self.model_policy(config, provider_family)
           cfg = config.is_a?(Hash) ? config : {}
           provider_conf = CredentialSources.setting(:extensions, :llm, provider_family)
           provider_conf = {} unless provider_conf.is_a?(Hash)
+          global_conf = (::Legion::Settings.dig(:extensions, :llm) if defined?(::Legion::Settings))
+          global_conf = {} unless global_conf.is_a?(Hash)
+
           {
-            whitelist: cfg[:model_whitelist] || provider_conf[:model_whitelist] || provider_conf['model_whitelist'],
-            blacklist: cfg[:model_blacklist] || provider_conf[:model_blacklist] || provider_conf['model_blacklist']
+            whitelist: resolve_policy_value(cfg, provider_conf, global_conf, :model_whitelist),
+            blacklist: resolve_policy_value(cfg, provider_conf, global_conf, :model_blacklist)
           }
         end
 
+        # Resolve a single policy value with instance > provider > global precedence.
+        def self.resolve_policy_value(cfg, provider_conf, global_conf, key)
+          # Instance-level
+          val = cfg[key] || cfg[key.to_s]
+          return val if val && !val.to_s.empty? && (val.is_a?(Array) ? val.any? : true)
+
+          # Provider-level
+          val = provider_conf[key] || provider_conf[key.to_s]
+          return val if val && !val.to_s.empty? && (val.is_a?(Array) ? val.any? : true)
+
+          # Global
+          global_conf[key] || global_conf[key.to_s]
+        end
+
         # Choose a default_model that never violates the model policy: prefer an
         # explicitly-configured default when permitted; else a provider fallback when
         # permitted; else nil, so routing resolves an allowed discovered model rather
@@ -478,7 +623,7 @@ module Legion
           Socket.tcp(uri.host, uri.port, connect_timeout: 1).close
           true
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'llm.provider.url_reachable', url:)
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.url_reachable', url:)
           false
         end
 
@@ -501,7 +646,7 @@ module Legion
 
           cache_local_instance? ? local_cache_get(key) : cache_get(key)
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'llm.provider.model_cache_get', key:)
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.model_cache_get', key:)
           nil
         end
 
@@ -593,6 +738,33 @@ module Legion
 
         private
 
+        def provider_capability_config
+          return {} unless defined?(Legion::Extensions::Llm::CredentialSources)
+
+          raw = Legion::Extensions::Llm::CredentialSources.setting(:extensions, :llm, slug.to_sym)
+          return {} unless raw.respond_to?(:to_h)
+
+          raw.to_h.except(:instances, 'instances')
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: "#{slug}.provider_capability_config")
+          {}
+        end
+
+        def instance_capability_config
+          extract_capability_config(config)
+        end
+
+        def model_capability_config(model_id)
+          provider_models = provider_capability_models
+          instance_models = extract_models_config(config)
+          provider_override = provider_models[model_id.to_s] || provider_models[model_id.to_sym] || {}
+          instance_override = instance_models[model_id.to_s] || instance_models[model_id.to_sym] || {}
+          provider_override.to_h.merge(instance_override.to_h)
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: "#{slug}.model_capability_config")
+          {}
+        end
+
         def global_prompt_caching_enabled?
           return false unless defined?(Legion::Settings)
 
@@ -631,6 +803,34 @@ module Legion
           raise UnsupportedAttachmentError, "#{name} does not support image references in paint"
         end
 
+        def extract_capability_config(source)
+          return {} unless source
+
+          CAPABILITY_CONFIG_KEYS.each_with_object({}) do |key, result|
+            next unless source.respond_to?(key)
+
+            value = source.public_send(key)
+            result[key] = value unless value.nil?
+          rescue StandardError
+            next
+          end
+        end
+
+        def extract_models_config(source)
+          return {} unless source.respond_to?(:models)
+
+          models = source.models
+          models.respond_to?(:to_h) ? models.to_h : {}
+        rescue StandardError
+          {}
+        end
+
+        def provider_capability_models
+          config = provider_capability_config
+          models = config[:models] || config['models']
+          models.respond_to?(:to_h) ? models.to_h : {}
+        end
+
         def offering_from_model(model, health: {})
           capability_sources = Array(model.capabilities).to_h do |cap|
             [cap.to_sym, { value: true, source: :model_metadata }]
@@ -733,7 +933,11 @@ module Legion
         def health_status(readiness_data, raw_health)
           return 'healthy' if readiness_data[:ready] == true || readiness_data['ready'] == true
 
-          status = raw_health[:status] || raw_health['status'] || raw_health[:state] || raw_health['state']
+          status = if raw_health.is_a?(Hash)
+                     raw_health[:status] || raw_health['status'] || raw_health[:state] || raw_health['state']
+                   else
+                     raw_health
+                   end
           return 'healthy' if %w[ok ready healthy running].include?(status.to_s.downcase)
 
           'unhealthy'

data/lib/legion/extensions/llm/registry_event_builder.rb

@@ -63,12 +63,13 @@ module Legion
         end
 
         def readiness_health(readiness)
+          source = readiness[:health]
           health = {
             ready: readiness[:ready] == true,
             status: readiness[:ready] ? :available : :unavailable,
-            checked: readiness.dig(:health, :checked) != false
+            checked: !source.is_a?(Hash) || source[:checked] != false
           }
-          add_readiness_error(health, readiness[:health])
+          add_readiness_error(health, source)
         end
 
         def add_readiness_error(health, source)
@@ -126,7 +127,7 @@ module Legion
           value = configured_node.to_s.strip
           value.empty? ? provider_family : value.to_sym
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true,
+          handle_exception(e, level: :warn, handled: true,
                               operation: "#{provider_family}.registry.provider_instance")
           provider_family
         end

data/lib/legion/extensions/llm/registry_publisher.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'concurrent'
+
 module Legion
   module Extensions
     module Llm
@@ -9,6 +11,8 @@ module Legion
       class RegistryPublisher
         include Legion::Logging::Helper
 
+        ASYNC_THREAD_POOL = Concurrent::FixedThreadPool.new(1, fallback_policy: :caller_runs)
+
         attr_reader :provider_family
 
         def initialize(provider_family:, builder: nil)
@@ -21,12 +25,12 @@ module Legion
         end
 
         def publish_readiness_async(readiness)
-          log.info { "publishing readiness event to llm.registry for #{provider_family}" }
+          log.debug { "publishing readiness event to llm.registry for #{provider_family}" }
           schedule { publish_event(@builder.readiness(readiness)) }
         end
 
         def publish_models_async(models, readiness:)
-          log.info { "publishing #{Array(models).size} model event(s) to llm.registry for #{provider_family}" }
+          log.debug { "publishing #{Array(models).size} model event(s) to llm.registry for #{provider_family}" }
           schedule do
             Array(models).each do |model|
               publish_event(@builder.model_available(model, readiness:))
@@ -39,15 +43,14 @@ module Legion
         def schedule(&)
           return false unless publishing_available?
 
-          Thread.new do
-            Thread.current.abort_on_exception = false
+          ASYNC_THREAD_POOL.post do
             yield
           rescue StandardError => e
-            handle_exception(e, level: :debug, handled: true,
+            handle_exception(e, level: :warn, handled: true,
                                 operation: "#{provider_family}.registry.schedule_thread")
           end
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true,
+          handle_exception(e, level: :warn, handled: true,
                               operation: "#{provider_family}.registry.schedule")
           false
         end
@@ -70,7 +73,7 @@ module Legion
 
           ::Legion::Transport::Connection.session_open?
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true,
+          handle_exception(e, level: :warn, handled: true,
                               operation: "#{provider_family}.registry.publishing_available?")
           false
         end
@@ -86,7 +89,7 @@ module Legion
           require 'legion/extensions/llm/transport/messages/registry_event'
           message_class_defined?
         rescue LoadError => e
-          handle_exception(e, level: :debug, handled: true,
+          handle_exception(e, level: :warn, handled: true,
                               operation: "#{provider_family}.registry.transport_load")
           false
         end

data/lib/legion/extensions/llm/routing/model_offering.rb

@@ -159,21 +159,14 @@ module Legion
           end
 
           def normalize_capabilities(value)
-            Array(value).compact.each_with_object([]) do |item, normalized|
-              symbol = item.to_s.downcase.strip.to_sym
-              next if symbol.to_s.empty?
-
-              normalized << symbol
-              alias_symbol = CAPABILITY_ALIASES[symbol]
-              normalized << alias_symbol if alias_symbol
-            end.uniq
+            Legion::Extensions::Llm::Capabilities.normalize(value)
           end
 
           def normalize_capability_sources(value)
             normalize_hash(value).to_h do |capability, source_data|
               normalized_source = normalize_hash(source_data)
               [
-                capability.to_s.downcase.tr('-', '_').to_sym,
+                Legion::Extensions::Llm::Capabilities.canonical(capability),
                 { value: normalized_source[:value], source: normalized_source[:source]&.to_sym }.compact
               ]
             end

data/lib/legion/extensions/llm/taxonomies.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Taxonomies
+        TIERS           = %i[direct local fleet cloud frontier].freeze
+        TYPES           = %i[inference embedding image audio].freeze
+        CIRCUIT_STATES  = %i[closed half_open open].freeze
+        HEALTH_KEYS     = %i[circuit_state denied available adjustment].freeze
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.5.4'
+      VERSION = '0.6.2'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -36,6 +36,12 @@ module Legion
       #  unqualified constant lookups resolve via Ruby scope.               #
       # ------------------------------------------------------------------ #
 
+      # --- P1 SSOT: taxonomy enums, capability normalization, inventory writer mixin ---
+      require_relative 'llm/taxonomies'
+      require_relative 'llm/capabilities'
+      require_relative 'llm/inventory/scoped_refresher'
+      require_relative 'llm/inventory/capabilities'
+
       # --- Capability resolution policy (no internal deps) ---
       require_relative 'llm/capability_policy'
 

data/spec/legion/extensions/llm/capabilities_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/capabilities'
+
+RSpec.describe Legion::Extensions::Llm::Capabilities do
+  describe '.normalize' do
+    it 'normalizes :function_calling to :tools' do
+      expect(described_class.normalize([:function_calling])).to include(:tools)
+    end
+
+    it 'normalizes :tool_use to :tools' do
+      expect(described_class.normalize([:tool_use])).to include(:tools)
+    end
+
+    it 'passes through unknown capabilities unchanged' do
+      expect(described_class.normalize([:vision])).to include(:vision)
+    end
+
+    it 'returns frozen array' do
+      expect(described_class.normalize([:tools])).to be_frozen
+    end
+
+    it 'handles nil/empty input gracefully' do
+      expect(described_class.normalize(nil)).to eq([])
+      expect(described_class.normalize([])).to eq([])
+    end
+  end
+
+  describe '.include_all?' do
+    it 'returns true when required caps are a subset of available' do
+      expect(described_class.include_all?(%i[tools vision], [:tools])).to be true
+    end
+
+    it 'returns false when a required cap is missing' do
+      expect(described_class.include_all?([:vision], [:tools])).to be false
+    end
+
+    it 'matches :function_calling against :tools via alias (PR #152 I1)' do
+      expect(described_class.include_all?([:function_calling], [:tools])).to be true
+    end
+  end
+
+  describe '.merge' do
+    it 'merges and deduplicates multiple capability sets' do
+      result = described_class.merge([:tools], %i[vision tools])
+      expect(result.count(:tools)).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/llm/capability_policy_spec.rb

@@ -14,7 +14,7 @@ RSpec.describe Legion::Extensions::Llm::CapabilityPolicy do
         policy = described_class.resolve(**empty_sources)
 
         expect(policy[:capabilities]).to eq([])
-        expect(policy[:sources][:embeddings]).to eq(value: false, source: :default_false)
+        expect(policy[:sources][:embedding]).to eq(value: false, source: :default_false)
         expect(policy[:sources][:thinking]).to eq(value: false, source: :default_false)
         expect(policy[:sources][:streaming]).to eq(value: false, source: :default_false)
         expect(policy[:sources][:tools]).to eq(value: false, source: :default_false)
@@ -42,7 +42,7 @@ RSpec.describe Legion::Extensions::Llm::CapabilityPolicy do
 
         expect(policy[:capabilities]).to contain_exactly(:streaming, :tools, :thinking)
         expect(policy[:sources][:thinking]).to eq(value: true, source: :instance_override)
-        expect(policy[:sources][:embeddings]).to eq(value: false, source: :provider_override)
+        expect(policy[:sources][:embedding]).to eq(value: false, source: :provider_override)
         expect(policy[:sources][:tools]).to eq(value: true, source: :instance_override)
       end
     end
@@ -65,7 +65,7 @@ RSpec.describe Legion::Extensions::Llm::CapabilityPolicy do
 
         expect(policy[:capabilities]).to contain_exactly(:streaming, :thinking)
         expect(policy[:sources][:streaming]).to eq(value: true, source: :provider_override)
-        expect(policy[:sources][:embeddings]).to eq(value: false, source: :provider_override)
+        expect(policy[:sources][:embedding]).to eq(value: false, source: :provider_override)
         expect(policy[:sources][:thinking]).to eq(value: true, source: :provider_override)
       end
     end
@@ -82,11 +82,11 @@ RSpec.describe Legion::Extensions::Llm::CapabilityPolicy do
           model_config: { capabilities: { tools: true } }
         )
 
-        expect(policy[:capabilities]).to include(:tools, :embeddings, :streaming, :structured_output)
+        expect(policy[:capabilities]).to include(:tools, :embedding, :streaming, :structured_output)
         expect(policy[:capabilities]).not_to include(:vision)
         expect(policy[:sources][:tools]).to eq(value: true, source: :model_override)
         expect(policy[:sources][:vision]).to eq(value: false, source: :provider_override)
-        expect(policy[:sources][:embeddings]).to eq(value: true, source: :probe)
+        expect(policy[:sources][:embedding]).to eq(value: true, source: :probe)
         expect(policy[:sources][:structured_output]).to eq(value: true, source: :provider_catalog)
         expect(policy[:sources][:streaming]).to eq(value: true, source: :provider_envelope)
       end
@@ -109,6 +109,29 @@ RSpec.describe Legion::Extensions::Llm::CapabilityPolicy do
         expect(policy[:sources][:streaming]).to eq(value: true, source: :instance_override)
         expect(policy[:sources][:tools]).to eq(value: false, source: :instance_override)
       end
+
+      it 'canonicalizes reasoning, embedding, and image-generation aliases' do
+        policy = described_class.resolve(
+          real: {},
+          provider_catalog: {},
+          probe: {},
+          provider_envelope: {},
+          provider_config: {},
+          instance_config: {
+            enable_reasoning: true,
+            embeddings_flag: true,
+            image_generation_flag: true,
+            completion_flag: true
+          },
+          model_config: {}
+        )
+
+        expect(policy[:capabilities]).to include(:thinking, :embedding, :image, :completion)
+        expect(policy[:sources][:thinking]).to eq(value: true, source: :instance_override)
+        expect(policy[:sources][:embedding]).to eq(value: true, source: :instance_override)
+        expect(policy[:sources][:image]).to eq(value: true, source: :instance_override)
+        expect(policy[:sources][:completion]).to eq(value: true, source: :instance_override)
+      end
     end
 
     context 'when capabilities hash wins over alias at same level' do

data/spec/legion/extensions/llm/inventory/capabilities_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Capabilities do
+  describe '.normalize' do
+    it 'returns symbols for raw capability names' do
+      expect(described_class.normalize(%i[tools streaming])).to contain_exactly(:tools, :streaming)
+    end
+
+    it 'collapses provider aliases into the canonical vocabulary' do
+      expect(described_class.normalize([:function_calling])).to include(:tools)
+      expect(described_class.normalize([:tool_use])).to include(:tools)
+      expect(described_class.normalize([:stream])).to include(:streaming)
+    end
+
+    it 'returns an empty array for nil/empty input' do
+      expect(described_class.normalize(nil)).to eq([])
+      expect(described_class.normalize([])).to eq([])
+    end
+
+    it 'is the same vocabulary as Legion::Extensions::Llm::Capabilities' do
+      expect(described_class::ALIASES).to equal(Legion::Extensions::Llm::Capabilities::ALIASES)
+    end
+  end
+
+  describe '.merge' do
+    it 'unions multiple capability sets' do
+      result = described_class.merge([:tools], %i[streaming tools])
+      expect(result).to contain_exactly(:tools, :streaming)
+    end
+  end
+
+  describe '.include_all?' do
+    it 'returns true when required is a subset of available' do
+      expect(described_class.include_all?(%i[tools streaming], [:tools])).to be(true)
+    end
+
+    it 'returns false when required is missing from available' do
+      expect(described_class.include_all?([:streaming], [:tools])).to be(false)
+    end
+  end
+end