lex-llm 0.6.16 → 0.7.2

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

@@ -57,4 +57,24 @@ RSpec.describe Legion::Extensions::Llm::ProviderContract do
     expect { provider.image('prompt', model: 'model') }.to raise_error(ArgumentError)
     expect { provider.count_tokens([], model: 'model') }.to raise_error(ArgumentError)
   end
+
+  it 'keeps REQUIRED_SIGNATURES as exactly the eight-entry reflection baseline' do
+    expect(described_class::REQUIRED_SIGNATURES).to eq(
+      chat: [%i[keyreq messages], %i[keyreq model]],
+      stream_chat: [%i[keyreq messages], %i[keyreq model]],
+      embed: [%i[keyreq text], %i[keyreq model]],
+      image: [%i[keyreq prompt], %i[keyreq model]],
+      list_models: [%i[key live], %i[keyrest filters]],
+      discover_offerings: [%i[key live], %i[key raise_on_unreachable], %i[keyrest filters]],
+      health: [%i[key live]],
+      count_tokens: [%i[keyreq messages], %i[keyreq model], %i[key params]]
+    )
+  end
+
+  it 'does not smuggle optional operations or image.size into the reflection baseline' do
+    %i[size transcribe moderate disconnect speak translate normalize_dispatch_error].each do |operation|
+      expect(described_class::REQUIRED_SIGNATURES).not_to have_key(operation)
+    end
+    expect(described_class::REQUIRED_SIGNATURES[:image]).to eq([%i[keyreq prompt], %i[keyreq model]])
+  end
 end

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

@@ -742,4 +742,87 @@ RSpec.describe Legion::Extensions::Llm::Provider do
       expect { provider.disconnect }.not_to raise_error
     end
   end
+
+  describe 'fail-loud base audio operations' do
+    let(:provider) do
+      Class.new(described_class) do
+        def api_base = 'https://test.invalid'
+        def ensure_configured! = nil
+      end.new(request_timeout: 30, max_retries: 0, retry_interval: 0, retry_backoff_factor: 0, retry_interval_randomness: 0)
+    end
+
+    it 'raises NotImplementedError from translate without inferring a model' do
+      expect { provider.translate('audio', model: 'm', language: 'en') }
+        .to raise_error(NotImplementedError, /translate/)
+    end
+
+    it 'raises NotImplementedError from speak' do
+      expect { provider.speak('hello', model: 'm') }.to raise_error(NotImplementedError, /speak/)
+    end
+
+    it 'declares the protected keyword signatures without joining REQUIRED_SIGNATURES' do
+      translate_params = described_class.instance_method(:translate).parameters
+      expect(translate_params).to include(%i[req audio_file], %i[keyreq model], %i[keyreq language])
+      speak_params = described_class.instance_method(:speak).parameters
+      expect(speak_params).to include(%i[req text], %i[keyreq model], %i[key voice])
+      expect(Legion::Extensions::Llm::ProviderContract::REQUIRED_SIGNATURES).not_to have_key(:translate)
+      expect(Legion::Extensions::Llm::ProviderContract::REQUIRED_SIGNATURES).not_to have_key(:speak)
+    end
+  end
+
+  describe '#normalize_dispatch_error' do
+    llm = Legion::Extensions::Llm
+
+    let(:provider) do
+      Class.new(described_class) do
+        def api_base = 'https://test.invalid'
+        def ensure_configured! = nil
+      end.new(request_timeout: 30, max_retries: 0, retry_interval: 0, retry_backoff_factor: 0, retry_interval_randomness: 0)
+    end
+
+    it 'returns a Routing::ProviderOutcome and is not a REQUIRED_SIGNATURES entry' do
+      outcome = provider.normalize_dispatch_error(error: StandardError.new('x'))
+      expect(outcome).to be_a(Legion::Extensions::Llm::Routing::ProviderOutcome)
+      expect(Legion::Extensions::Llm::ProviderContract::REQUIRED_SIGNATURES).not_to have_key(:normalize_dispatch_error)
+    end
+
+    it 'maps the conservative typed error table' do
+      {
+        llm::OverloadedError.new('overloaded') => :overloaded,
+        llm::RateLimitError.new('rate') => :rate_limited,
+        llm::UnauthorizedError.new('auth') => :authentication,
+        llm::PaymentRequiredError.new('pay') => :billing,
+        llm::ForbiddenError.new('forbidden') => :authorization,
+        llm::ContextLengthExceededError.new('ctx') => :context_rejected,
+        llm::BadRequestError.new('bad') => :invalid_request,
+        llm::ModelNotFoundError.new('missing') => :model_missing,
+        llm::ModelNotAllowedError.new('denied') => :policy,
+        Faraday::TimeoutError.new('timeout') => :timeout,
+        Faraday::ConnectionFailed.new('conn') => :connection_failure
+      }.each do |error, expected_kind|
+        expect(provider.normalize_dispatch_error(error: error).kind).to eq(expected_kind)
+      end
+    end
+
+    it 'never maps raw 503/529, ServiceUnavailableError, ServerError, or unknown errors to instance_unavailable' do
+      [
+        llm::Error.new('raw 503 body'),
+        llm::Error.new('raw 529 body'),
+        llm::ServiceUnavailableError.new('503'),
+        llm::ServerError.new('500'),
+        StandardError.new('unexpected'),
+        RuntimeError.new('boom')
+      ].each do |error|
+        outcome = provider.normalize_dispatch_error(error: error)
+        expect(outcome.kind).to eq(:provider_error)
+        expect(outcome.kind).not_to eq(:instance_unavailable)
+      end
+    end
+
+    it 'uses only the bounded exception class name as reason and never copies the response body' do
+      outcome = provider.normalize_dispatch_error(error: llm::OverloadedError.new(nil, 'super-secret-response-body'))
+      expect(outcome.reason).to eq('Legion::Extensions::Llm::OverloadedError')
+      expect(outcome.reason).not_to include('super-secret-response-body')
+    end
+  end
 end

data/spec/legion/extensions/llm/routing/provider_outcome_spec.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/routing/provider_outcome'
+
+RSpec.describe Legion::Extensions::Llm::Routing::ProviderOutcome do
+  inventory = Legion::Extensions::Llm::Inventory
+  routing = Legion::Extensions::Llm::Routing
+  errors = inventory::Errors
+
+  it 'builds a normalized outcome for each canonical kind' do
+    outcome = described_class.new(kind: :success, reason: 'ok')
+    expect(outcome.kind).to eq(:success)
+    expect(outcome.metadata).to be_frozen
+  end
+
+  it 'rejects a kind outside PROVIDER_OUTCOMES' do
+    expect { described_class.new(kind: :made_up, reason: 'x') }.to raise_error(errors::ValidationError)
+  end
+
+  it 'has no HTTP status field: 503/529 cannot be an input' do
+    expect(described_class.members).not_to include(:http_status, :status_code)
+    expect(described_class.new(kind: :overloaded, reason: '503 overloaded').kind).to eq(:overloaded)
+  end
+
+  it 'never manufactures instance_unavailable from a raw status; only an explicit kind does' do
+    # An adapter that received HTTP 503 overload constructs :overloaded, not :instance_unavailable.
+    overloaded = described_class.new(kind: :overloaded, reason: 'HTTP 503 overloaded')
+    expect(overloaded.kind).not_to eq(:instance_unavailable)
+    # instance_unavailable exists only when an adapter explicitly constructs that kind.
+    explicit = described_class.new(kind: :instance_unavailable, reason: 'service unavailable')
+    expect(explicit.kind).to eq(:instance_unavailable)
+  end
+
+  it 'allows a quota_domain only for rate_limited' do
+    domain = routing::QuotaDomainKey.new(provider_family: 'vllm', opaque_id: 'q1')
+    expect(described_class.new(kind: :rate_limited, reason: 'quota', quota_domain: domain).quota_domain).to eq(domain)
+    expect { described_class.new(kind: :timeout, reason: 'x', quota_domain: domain) }
+      .to raise_error(errors::ValidationError)
+  end
+
+  it 'requires quota_domain to be a QuotaDomainKey' do
+    expect { described_class.new(kind: :rate_limited, reason: 'x', quota_domain: 'q1') }
+      .to raise_error(errors::ValidationError)
+  end
+
+  it 'accepts a finite nonnegative retry_after and rejects negatives/infinity' do
+    expect(described_class.new(kind: :rate_limited, reason: 'x', retry_after: 1.5).retry_after).to eq(1.5)
+    expect { described_class.new(kind: :rate_limited, reason: 'x', retry_after: -1) }
+      .to raise_error(errors::ValidationError)
+    expect { described_class.new(kind: :rate_limited, reason: 'x', retry_after: (1.0 / 0.0)) }
+      .to raise_error(errors::ValidationError)
+  end
+
+  it 'rejects secret metadata' do
+    expect { described_class.new(kind: :success, reason: 'ok', metadata: { api_key: 'x' }) }
+      .to raise_error(errors::ValidationError)
+  end
+
+  it 'coerces a non-UTF-8 (binary) provider error reason to valid UTF-8 instead of raising' do
+    # Regression guard (root cause A): RecordSupport.sanitized_reason previously raised
+    # ValidationError 'is not valid UTF-8' on an ASCII-8BIT/BINARY reason (a raw provider
+    # error body or Ruby kernel error message), masking the real dispatch error as an
+    # unclassifiable retriable 500. It now coerces to valid UTF-8 (undecodable bytes
+    # replaced), so a provider error can no longer mask itself.
+    raw = "provider 500 \xFF\x80 body".dup.force_encoding(Encoding::BINARY)
+    expect { described_class.new(kind: :provider_error, reason: raw) }.not_to raise_error
+
+    outcome = described_class.new(kind: :provider_error, reason: raw)
+    expect(outcome.kind).to eq(:provider_error)
+    expect(outcome.reason.valid_encoding?).to be(true)
+  end
+end

data/spec/legion/extensions/llm/routing/records_spec.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/routing/records'
+
+RSpec.describe Legion::Extensions::Llm::Routing::Records do
+  inventory = Legion::Extensions::Llm::Inventory
+  routing = Legion::Extensions::Llm::Routing
+  errors = inventory::Errors
+  identity = inventory::Identity
+
+  let(:callable_class) do
+    Class.new do
+      def disconnect; end
+    end
+  end
+  let(:callable_handle) { inventory::CallableHandle.new(handle_id: 'call:v1:x', callable: callable_class.new) }
+  let(:instance_key) { identity::InstanceKey.new(provider_family: 'vllm', instance_id: 'h200') }
+  let(:offering_id) { identity.offering_id(instance_key: instance_key, provider_native_key: 'gemma4') }
+  let(:lane_id) do
+    identity.lane_id(instance_key: instance_key, operation: :chat, model: 'gemma4', offering_id: offering_id)
+  end
+
+  describe routing::AttemptTargetKey do
+    it 'treats the same model on two instances as distinct keys' do
+      a = described_class.new(provider_family: 'vllm', instance_id: 'h200', model: 'gemma4')
+      b = described_class.new(provider_family: 'vllm', instance_id: 'helios1', model: 'gemma4')
+      expect(a).not_to eq(b)
+    end
+
+    it 'is value-equal for equal normalized fields and hashes equally' do
+      a = described_class.new(provider_family: 'vllm', instance_id: 'h200', model: 'gemma4')
+      b = described_class.new(provider_family: :vllm, instance_id: '  h200 ', model: 'gemma4')
+      expect(a).to eq(b)
+      expect(a.hash).to eq(b.hash)
+    end
+
+    it 'contains only provider_family, instance_id, and model' do
+      key = described_class.new(provider_family: 'vllm', instance_id: 'h200', model: 'gemma4')
+      expect(key.to_h.keys).to contain_exactly(:provider_family, :instance_id, :model)
+    end
+  end
+
+  describe routing::QuotaDomainKey do
+    it 'never compares equal across provider families' do
+      a = described_class.new(provider_family: 'vllm', opaque_id: 'q1')
+      b = described_class.new(provider_family: 'openai', opaque_id: 'q1')
+      expect(a).not_to eq(b)
+    end
+  end
+
+  describe routing::Exclusion do
+    it 'requires the target class to match the target_kind' do
+      expect do
+        described_class.new(target_kind: :instance, target: instance_key, reason: 'x', evidence: {}, lifetime: :request)
+      end.not_to raise_error
+      expect do
+        described_class.new(target_kind: :instance, target: 'nope', reason: 'x', evidence: {}, lifetime: :request)
+      end.to raise_error(errors::ValidationError)
+    end
+
+    it 'normalizes a provider target to a canonical Symbol' do
+      exclusion = described_class.new(target_kind: :provider, target: 'VLLM', reason: 'x', evidence: {}, lifetime: :request)
+      expect(exclusion.target).to eq(:vllm)
+    end
+
+    it 'freezes evidence and rejects an invalid lifetime' do
+      exclusion = described_class.new(target_kind: :model, target: 'gemma4', reason: 'x', evidence: { a: 1 }, lifetime: :attempt_group)
+      expect(exclusion.evidence).to be_frozen
+      expect do
+        described_class.new(target_kind: :model, target: 'gemma4', reason: 'x', evidence: {}, lifetime: :forever)
+      end.to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe routing::Selection do
+    def build_selection(**overrides)
+      Legion::Extensions::Llm::Routing::Selection.new(
+        inventory_generation: 7, lane_id: lane_id, instance_key: instance_key, offering_id: offering_id,
+        provider_family: :vllm, instance_id: 'h200', model: 'gemma4', operation: :chat,
+        callable_handle: callable_handle, publisher_token_id: 'ptok:v1:abc', capability_evidence: {},
+        context_evidence: Legion::Extensions::Llm::Inventory::ValueEvidence.new(status: :unknown, source: :absent),
+        weight_inputs: { tier: 2, provider: 3, instance: 5, model_or_offering: 7 },
+        base_weight: 210, preference_ppm: 1_000_000, effective_weight: 210_000_000,
+        rendezvous_score: 12_345, **overrides
+      )
+    end
+
+    it 'builds a valid selection and derives the attempt target key' do
+      selection = build_selection
+      key = selection.attempt_target_key
+      expect(key).to eq(routing::AttemptTargetKey.new(provider_family: :vllm, instance_id: 'h200', model: 'gemma4'))
+    end
+
+    it 'requires base_weight to equal the product of weight_inputs' do
+      expect { build_selection(base_weight: 211) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'requires effective_weight to equal base_weight * preference_ppm' do
+      expect { build_selection(effective_weight: 1) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'bounds preference_ppm to 500_000..1_500_000' do
+      expect { build_selection(preference_ppm: 400_000, effective_weight: 210 * 400_000) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a lane_id that does not reproduce' do
+      expect { build_selection(lane_id: "lane:v1:#{'0' * 64}") }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a publisher_token_id without the ptok:v1: prefix' do
+      expect { build_selection(publisher_token_id: 'nope') }.to raise_error(errors::ValidationError)
+    end
+
+    it 'freezes weight_inputs' do
+      expect(build_selection.weight_inputs).to be_frozen
+    end
+  end
+
+  describe routing::Rejection do
+    def build_rejection(**overrides)
+      Legion::Extensions::Llm::Routing::Rejection.new(
+        kind: :too_early, reason: 'initializing', inventory_generation: 0, candidate_counts: { eligible: 0 }, **overrides
+      )
+    end
+
+    it 'validates kind and freezes candidate_counts' do
+      rejection = build_rejection
+      expect(rejection.candidate_counts).to be_frozen
+      expect { build_rejection(kind: :made_up) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects candidate_counts with non-Symbol keys or negative values' do
+      expect { build_rejection(candidate_counts: { 'x' => 1 }) }.to raise_error(errors::ValidationError)
+      expect { build_rejection(candidate_counts: { eligible: -1 }) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'allows only provider/instance/model/tier explicit pins' do
+      expect { build_rejection(explicit_pins: { provider: 'vllm', tier: 'local' }) }.not_to raise_error
+      expect { build_rejection(explicit_pins: { secret: 'x' }) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'bounds http_status to 100..599' do
+      expect { build_rejection(http_status: 700) }.to raise_error(errors::ValidationError)
+      expect(build_rejection(http_status: 503).http_status).to eq(503)
+    end
+  end
+
+  describe routing::BodyModelHintDecision do
+    it 'allows only honored to carry a model_constraint' do
+      expect do
+        described_class.new(
+          requested_model: 'gemma4', disposition: :honored, model_constraint: 'gemma4', settings_generation: 1
+        )
+      end.not_to raise_error
+      expect do
+        described_class.new(
+          requested_model: 'gemma4', disposition: :auto, model_constraint: 'gemma4', settings_generation: 1
+        )
+      end.to raise_error(errors::ValidationError)
+    end
+
+    it 'requires absent to carry a nil requested_model' do
+      expect do
+        described_class.new(requested_model: 'gemma4', disposition: :absent, settings_generation: 1)
+      end.to raise_error(errors::ValidationError)
+      expect do
+        described_class.new(requested_model: nil, disposition: :absent, settings_generation: 1)
+      end.not_to raise_error
+    end
+  end
+end

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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::SettingsCascade do
+  let(:llm_conf) do
+    {
+      vllm: {
+        weight: 5,
+        model_whitelist: %w[gpt],
+        models: {
+          'alpha' => { weight: 11, enable_tools: true }
+        },
+        instances: {
+          apollo: {
+            weight: 7,
+            enable_tools: false,
+            models: {
+              'alpha' => { weight: 13 },
+              'beta' => { enable_tools: true, preferred_min_context_tokens: 100 }
+            }
+          },
+          'string-keyed' => { weight: 9 }
+        }
+      },
+      ollama: {
+        instances: { local: {} }
+      }
+    }
+  end
+
+  describe '.resolve_value (pure 3-level cascade, most-specific-first)' do
+    let(:provider_conf) { llm_conf[:vllm] }
+    let(:instance_conf) { llm_conf[:vllm][:instances][:apollo] }
+
+    it 'resolves the provider leg when no more specific scope carries the key' do
+      expect(described_class.resolve_value(provider_conf: provider_conf, instance_cfg: {}, key: :weight)).to eq(5)
+    end
+
+    it 'resolves the instance leg over the provider leg' do
+      expect(described_class.resolve_value(provider_conf: provider_conf, instance_cfg: instance_conf, key: :weight)).to eq(7)
+    end
+
+    it 'resolves the instance-scoped model leg over the provider-scoped model leg' do
+      result = described_class.resolve_value(
+        provider_conf: provider_conf, instance_cfg: instance_conf, key: :weight, model: 'alpha'
+      )
+      expect(result).to eq(13) # instance models.alpha (13) beats provider models.alpha (11) and instance weight (7)
+    end
+
+    it 'resolves the provider-scoped model leg when the instance model map has no entry' do
+      result = described_class.resolve_value(
+        provider_conf: provider_conf, instance_cfg: {}, key: :weight, model: 'alpha'
+      )
+      expect(result).to eq(11)
+    end
+
+    it 'resolves the model leg before the instance leg (most-specific-first)' do
+      result = described_class.resolve_value(
+        provider_conf: provider_conf, instance_cfg: instance_conf, key: :enable_tools, model: 'alpha'
+      )
+      # provider models.alpha.enable_tools (true) wins over instance enable_tools (false):
+      # the model leg is consulted before the instance leg
+      expect(result).to be(true)
+    end
+
+    it 'skips a model with no model-map entries and falls through to instance/provider' do
+      result = described_class.resolve_value(
+        provider_conf: provider_conf, instance_cfg: instance_conf, key: :weight, model: 'gamma'
+      )
+      expect(result).to eq(7)
+    end
+
+    it 'returns nil when no scope carries the key' do
+      expect(described_class.resolve_value(provider_conf: provider_conf, instance_cfg: instance_conf, key: :missing)).to be_nil
+      expect(described_class.resolve_value(provider_conf: {}, instance_cfg: {}, key: :weight)).to be_nil
+    end
+
+    context 'with empty values in scopes' do
+      it 'skips nil, blank String, and empty Array values, falling through to the next scope' do
+        conf = {
+          weight: '',
+          model_whitelist: [],
+          instances: { apollo: { weight: nil, model_whitelist: %w[claude], model_blacklist: [] } }
+        }
+        # instance nil + provider '' both skip -> nil
+        expect(described_class.resolve_value(provider_conf: conf, instance_cfg: conf[:instances][:apollo], key: :weight)).to be_nil
+        # instance '' / provider [] : a meaningful instance value resolves, an empty one falls to provider (empty -> nil)
+        expect(described_class.resolve_value(provider_conf: {}, instance_cfg: conf[:instances][:apollo], key: :model_whitelist)).to eq(%w[claude])
+        expect(described_class.resolve_value(provider_conf: conf, instance_cfg: {}, key: :model_whitelist)).to be_nil
+        # instance [] + provider absent -> nil
+        expect(described_class.resolve_value(provider_conf: conf, instance_cfg: conf[:instances][:apollo], key: :model_blacklist)).to be_nil
+      end
+
+      it 'does NOT skip meaningful non-String values (false, 0)' do
+        conf = { enable_thinking: false, weight: 0 }
+        expect(described_class.resolve_value(provider_conf: conf, instance_cfg: {}, key: :enable_thinking)).to be(false)
+        expect(described_class.resolve_value(provider_conf: conf, instance_cfg: {}, key: :weight)).to eq(0)
+      end
+
+      it 'skips empty values in model scopes too' do
+        conf = {
+          models: { 'alpha' => { weight: '', enable_tools: true } },
+          instances: { apollo: { models: { 'alpha' => { enable_tools: false, weight: [] } } } }
+        }
+        # instance model weight [] skipped, provider model weight '' skipped, no instance/provider weight -> nil
+        expect(
+          described_class.resolve_value(provider_conf: conf, instance_cfg: conf[:instances][:apollo], key: :weight, model: 'alpha')
+        ).to be_nil
+        # instance model enable_tools false is meaningful and wins
+        expect(
+          described_class.resolve_value(provider_conf: conf, instance_cfg: conf[:instances][:apollo], key: :enable_tools, model: 'alpha')
+        ).to be(false)
+      end
+    end
+
+    context 'with String and Symbol key/name variants' do
+      it 'accepts String or Symbol keys and instance/model names' do
+        expect(described_class.resolve_value(provider_conf: provider_conf, instance_cfg: instance_conf, key: 'weight')).to eq(7)
+        expect(described_class.resolve_value(provider_conf: provider_conf, instance_cfg: {}, key: :weight, model: :alpha)).to eq(11)
+        expect(
+          described_class.resolve_from(llm_conf: llm_conf, provider_family: 'vllm', instance: :apollo, key: :weight)
+        ).to eq(7)
+      end
+
+      it 'accepts string-keyed settings hashes (YAML/JSON variants)' do
+        conf = { 'vllm' => { 'weight' => 3, 'instances' => { 'apollo' => { 'weight' => 4 } } } }
+        expect(described_class.resolve_from(llm_conf: conf, provider_family: :vllm, instance: 'apollo', key: :weight)).to eq(4)
+      end
+
+      it 'tolerates non-Hash scopes' do
+        expect(described_class.resolve_value(provider_conf: nil, instance_cfg: nil, key: :weight)).to be_nil
+        expect(described_class.resolve_from(llm_conf: nil, provider_family: :vllm, instance: 'apollo', key: :weight)).to be_nil
+      end
+    end
+
+    context 'with invalid argument types' do
+      it 'rejects non-text keys, instances, models, and provider families' do
+        expect { described_class.resolve_value(provider_conf: provider_conf, instance_cfg: {}, key: 5) }
+          .to raise_error(ArgumentError, /key must be a String or Symbol/)
+        expect { described_class.resolve_value(provider_conf: provider_conf, instance_cfg: {}, key: :weight, model: 5) }
+          .to raise_error(ArgumentError, /model must be a String or Symbol/)
+        expect { described_class.resolve_from(llm_conf: llm_conf, provider_family: 5, instance: 'a', key: :k) }
+          .to raise_error(ArgumentError, /provider_family must be a String or Symbol/)
+        expect { described_class.resolve_from(llm_conf: llm_conf, provider_family: :vllm, instance: 5, key: :k) }
+          .to raise_error(ArgumentError, /instance must be a String or Symbol/)
+      end
+    end
+  end
+
+  describe '.merge_model_scopes (capability-feeder merge)' do
+    it 'merges the provider models.<model> entry with the instance models.<model> entry overriding it' do
+      merged = described_class.merge_model_scopes(
+        provider_conf: llm_conf[:vllm],
+        instance_cfg: llm_conf[:vllm][:instances][:apollo],
+        model: 'alpha'
+      )
+      expect(merged).to eq(weight: 13, enable_tools: true)
+    end
+
+    it 'returns {} when no scope carries a models map' do
+      expect(described_class.merge_model_scopes(provider_conf: {}, instance_cfg: {}, model: 'alpha')).to eq({})
+    end
+
+    it 'ignores non-Hash model entries' do
+      conf = { models: { 'alpha' => 'not-a-hash' } }
+      expect(described_class.merge_model_scopes(provider_conf: conf, instance_cfg: {}, model: 'alpha')).to eq({})
+    end
+  end
+
+  describe '.resolve (live Legion::Settings path)' do
+    around do |example|
+      saved = Legion::Settings.loader.settings[:extensions]
+      example.run
+    ensure
+      if saved.nil?
+        Legion::Settings.loader.settings.delete(:extensions)
+      else
+        Legion::Settings.loader.settings[:extensions] = saved
+      end
+    end
+
+    it 'reads the real nested extensions.llm.<provider> path, keyed by the config name' do
+      Legion::Settings.loader.settings[:extensions] = { llm: llm_conf }
+
+      expect(described_class.resolve(provider_family: :vllm, instance: 'apollo', key: :weight)).to eq(7)
+      expect(described_class.resolve(provider_family: :vllm, instance: 'apollo', key: :weight, model: 'alpha')).to eq(13)
+      expect(described_class.resolve(provider_family: :vllm, instance: 'nobody', key: :model_whitelist)).to eq(%w[gpt])
+      expect(described_class.resolve(provider_family: :vllm, instance: 'nobody', key: :missing)).to be_nil
+      expect(described_class.resolve(provider_family: :nope, instance: 'apollo', key: :weight)).to be_nil
+    end
+
+    it 'returns nil when no extensions.llm subtree exists at all' do
+      Legion::Settings.loader.settings[:extensions] = {}
+      expect(described_class.resolve(provider_family: :vllm, instance: 'apollo', key: :weight)).to be_nil
+    end
+  end
+
+  describe '.resolve_from (frozen subtree, e.g. a router settings snapshot)' do
+    it 'resolves the same cascade against a pre-fetched extensions.llm hash' do
+      frozen_subtree = llm_conf
+      expect(described_class.resolve_from(llm_conf: frozen_subtree, provider_family: :vllm, instance: 'apollo', key: :weight)).to eq(7)
+      expect(
+        described_class.resolve_from(llm_conf: frozen_subtree, provider_family: :vllm, instance: 'string-keyed', key: :weight)
+      ).to eq(9)
+    end
+  end
+end

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

@@ -25,4 +25,55 @@ RSpec.describe Legion::Extensions::Llm::Taxonomies do
     expect(described_class::TYPES).to be_frozen
     expect(described_class::CIRCUIT_STATES).to be_frozen
   end
+
+  describe 'SSOT v3 enums' do
+    it 'OPERATIONS contains exactly the nine canonical operations' do
+      expect(described_class::OPERATIONS).to eq(
+        %i[chat stream_chat embed image transcribe translate speak moderate count_tokens]
+      )
+    end
+
+    it 'freezes every SSOT enum constant' do
+      %i[
+        OPERATIONS CAPABILITY_EVIDENCE_STATES OPERATION_EVIDENCE_STATES VALUE_EVIDENCE_STATES
+        AVAILABILITY_STATES AVAILABILITY_SOURCES PROBE_OUTCOMES PUBLICATION_STATES CALLABLE_STATES
+        MUTATION_REASONS PROVIDER_OUTCOMES REJECTION_KINDS EXCLUSION_TARGET_KINDS EXCLUSION_LIFETIMES
+        BODY_MODEL_HINT_DISPOSITIONS EVIDENCE_SOURCES UNKNOWN_ONLY_EVIDENCE_SOURCES
+      ].each { |const| expect(described_class.const_get(const)).to be_frozen }
+    end
+
+    it 'UNKNOWN_ONLY_EVIDENCE_SOURCES is a subset of EVIDENCE_SOURCES' do
+      expect(described_class::EVIDENCE_SOURCES).to include(*described_class::UNKNOWN_ONLY_EVIDENCE_SOURCES)
+    end
+  end
+
+  describe '.normalize_operation' do
+    it 'returns a canonical operation unchanged' do
+      expect(described_class.normalize_operation(value: 'chat')).to eq(:chat)
+      expect(described_class.normalize_operation(value: :stream_chat)).to eq(:stream_chat)
+    end
+
+    it 'accepts only the documented aliases when allow_aliases is true' do
+      {
+        stream: :stream_chat, embedding: :embed, moderation: :moderate,
+        audio_translation: :translate, speech: :speak
+      }.each do |input, canonical|
+        expect(described_class.normalize_operation(value: input, allow_aliases: true)).to eq(canonical)
+      end
+    end
+
+    it 'raises on an alias when allow_aliases is false' do
+      expect { described_class.normalize_operation(value: :stream) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+    end
+
+    it 'raises on unknown, empty, and invalid UTF-8 input' do
+      expect { described_class.normalize_operation(value: :nope) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+      expect { described_class.normalize_operation(value: '   ') }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+      expect { described_class.normalize_operation(value: "\xFF".b) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+    end
+  end
 end

data/spec/support/fake_llm_provider.rb

@@ -96,6 +96,17 @@ module SpecSupport
     def transcribe(_audio_file, model:, language:, **)
       Legion::Extensions::Llm::Transcription.new(text: 'fake transcript', model: model, language: language)
     end
+
+    # Records exactly-once disconnect for the callable-lifecycle contract; does
+    # not add disconnect to ProviderContract::REQUIRED_SIGNATURES.
+    def disconnect_count
+      @disconnect_count || 0
+    end
+
+    def disconnect
+      @disconnect_count = disconnect_count + 1
+      super
+    end
   end
 
   class BackupFakeLLMProvider < FakeLLMProvider