lex-llm 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6ab83cce686d4d63038e65c45039320fd61abf117acbde7ea05e4bca8ce1878
-  data.tar.gz: 768282bf56c16956f91a2be653e460e7d961775b8d782ad3177d9a637fb3a032
+  metadata.gz: e91ed0737e9946e5fce06f1a594f3139ea3f5dfd55e7e4a757fb66b77a099d13
+  data.tar.gz: 9284cbd89a01863b1d2226296b23d33250785b7988094d1b9e0223fb31cbbcb9
 SHA512:
-  metadata.gz: b9026c5963387e0c286bcdc80d7dceb61610fc5be4c67acf026b5e3ff59f95475edfdca79fb61f5910e5b143a02b946f36601679acc827fed55f1c998fe4148c
-  data.tar.gz: 2b896edf5d53f9d90c8ac6bdc410b84129d23f50640bd5a981e145d900f097294b3eeb7ffc60d696575a16974a47987eb5d30f8441b55f28041495d80bcc891a
+  metadata.gz: e8d7a88f398636313e23b74c8749b709e8400f5d67f86fa55f5d94cbfa2a9c1b4f47910d86020d0641ddfa2ae615de8759a9f6a233fdf53473c4dd48f0e7dd81
+  data.tar.gz: 443f471cf5875ddfa9995376cb3bbcce9a73cd16c3bcfffd3d1b101bb6e3fd0d1471c3c69052626b39b720909842f5e5a68961991a78bfee84a3d99488a971b6

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.7.2 - 2026-08-17
+
+### Fixed
+- **`Canonical::Message.from_hash` projects onto known member keys.** The factory now builds via `build(**h.slice(*members))` (mirroring `Request.from_hash`) instead of passing the raw hash to a fixed kwarg list, so transport-only keys such as `:cache_control` (injected by the prompt-cache step on multi-message requests) are dropped instead of raising `ArgumentError: unknown keyword: :cache_control` before the HTTP request was ever sent.
+- **`sanitized_reason` coerces non-UTF-8 reasons instead of raising.** Non-UTF-8 reasons (e.g. an ASCII-8BIT `ArgumentError` message) are now `force_encoding`'d to UTF-8 and `scrub`bed (`'?'`) rather than raising `ValidationError: reason is not valid UTF-8`, which masked the original dispatch error end-to-end (never logged) and produced a retriable 500. Non-String, empty, and oversized reasons still raise.
+
+### Added
+- **Regression specs for the dispatch-boundary fixes.** `Message.from_hash` with a transport-only `cache_control` key, and `ProviderOutcome` with a non-UTF-8 reason; both proven to fail pre-fix.
+- **legion-settings floor raised to `>= 1.4.2`.** Its segments-based nested resolution fixes two-segment extensions resolving to a flat key (e.g. `:llm_vllm`) instead of `[:extensions][:llm][:vllm]`, which left `settings[:instances]` nil so SSOT discovery actors saw zero configured instances.
+
+## 0.7.1 - 2026-08-14
+
+### Fixed
+- **Shared conformance fixtures now carry `metadata.model`.** SSOT v3 §9-compliant provider translators require an exact selected model to be present in the canonical request before `render_request` is called (they read `request.metadata[:model]`). The six request fixtures used by the shared `'a canonical provider translator'` examples previously carried no model, causing those conformance examples to fail for §9-compliant providers. Each fixture now includes `"metadata": { "model": "test-fixture-model" }`. No production behavior change; existing providers that fall back to a default model are unaffected.
+
 ## 0.7.0 - 2026-08-13
 
 ### Added

data/lex-llm.gemspec

@@ -40,7 +40,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-crypt', '>= 1.5.1'
   spec.add_dependency 'legion-json', '>= 1.2.1'
   spec.add_dependency 'legion-logging', '>= 1.3.2'
-  spec.add_dependency 'legion-settings', '>= 1.3.14'
+  spec.add_dependency 'legion-settings', '>= 1.4.2'
   spec.add_dependency 'legion-transport', '>= 1.4.14'
   spec.add_dependency 'marcel', '~> 1'
   spec.add_dependency 'ruby_llm-schema', '~> 0'

data/lib/legion/extensions/llm/canonical/message.rb

@@ -93,7 +93,11 @@ module Legion
               end
             end
 
-            build(**h)
+            # Tolerate transport-only keys (e.g. the prompt-cache step's :cache_control,
+            # injected onto every >=2-message request) by projecting onto the known
+            # member set — mirrors Canonical::Request.from_hash, which folds unknown keys
+            # instead of raising. Message has no metadata field, so unknown keys are dropped.
+            build(**h.slice(*members))
           end
 
           # Wrap input: pass through if already a Message, parse if Hash.

data/lib/legion/extensions/llm/inventory/identity.rb

@@ -101,15 +101,37 @@ module Legion
           # A mandatory, immutable provider_family + instance_id pair. Provider
           # family alone is never executable; two instances of the same provider
           # are independent targets. See section 8.1.
-          InstanceKey = ::Data.define(:provider_family, :instance_id) do
-            def initialize(provider_family:, instance_id:)
+          #
+          # instance_id is the operator's CONFIG NAME — the identity the router
+          # keys settings lookups (instances.<name>) by. physical_id is an
+          # optional SECONDARY field carrying the physical/derived id
+          # (e.g. "host:port" or "host:port/ak:<digest>") preserved for dedup
+          # and diagnostics. It is NOT identity: it never participates in
+          # equality, hashing, or registry-scope identity, so two config names
+          # pointing at the same endpoint stay distinct instances.
+          InstanceKey = ::Data.define(:provider_family, :instance_id, :physical_id) do
+            def initialize(provider_family:, instance_id:, physical_id: nil)
               family = Identity.normalize_text(value: provider_family, field: :provider_family).downcase
               raise Errors::ValidationError, 'provider_family must match /\A[a-z][a-z0-9_]*\z/' unless family.match?(/\A[a-z][a-z0-9_]*\z/)
 
               instance = Identity.normalize_text(value: instance_id, field: :instance_id)
               raise Errors::ValidationError, 'instance_id must not be the reserved value "default"' if instance == 'default'
 
-              super(provider_family: family.to_sym, instance_id: instance)
+              physical = physical_id.nil? ? nil : Identity.normalize_text(value: physical_id, field: :physical_id)
+
+              super(provider_family: family.to_sym, instance_id: instance, physical_id: physical)
+            end
+
+            # Identity is exactly (provider_family, instance_id). The
+            # secondary physical_id never affects equality, hashing, or
+            # registry-scope identity.
+            def ==(other)
+              other.is_a?(self.class) && other.provider_family == provider_family && other.instance_id == instance_id
+            end
+            alias_method :eql?, :==
+
+            def hash
+              [self.class, provider_family, instance_id].hash
             end
           end
         end

data/lib/legion/extensions/llm/inventory/publisher.rb

@@ -24,19 +24,25 @@ module Legion
             @compatibility_adapter = compatibility_adapter
           end
 
-          def claim_instance(instance_id:, callable:, probe_request_handle:)
-            key = instance_key(instance_id)
+          # Every instance operation takes `instance_id:` — the operator's
+          # CONFIG NAME (the identity the router keys by) — and an optional
+          # `physical_id:` carrying the physical/derived id (host:port/ak) for
+          # dedup and diagnostics only. See Identity::InstanceKey.
+          def claim_instance(instance_id:, callable:, probe_request_handle:, physical_id: nil)
+            key = instance_key(instance_id: instance_id, physical_id: physical_id)
             token = @registry.claim_instance(instance_key: key, callable: callable, probe_request_handle: probe_request_handle)
             sync_compatibility(key, :claimed)
             token
           end
 
-          def readiness_probe_started(instance_id:, publisher_token:)
-            @registry.readiness_probe_started(instance_key: instance_key(instance_id), publisher_token: publisher_token)
+          def readiness_probe_started(instance_id:, publisher_token:, physical_id: nil)
+            @registry.readiness_probe_started(
+              instance_key: instance_key(instance_id: instance_id, physical_id: physical_id), publisher_token: publisher_token
+            )
           end
 
-          def activate_instance_snapshot(instance_id:, publisher_token:, offerings:, sequence:, probe_token:)
-            key = instance_key(instance_id)
+          def activate_instance_snapshot(instance_id:, publisher_token:, offerings:, sequence:, probe_token:, physical_id: nil) # rubocop:disable Metrics/ParameterLists
+            key = instance_key(instance_id: instance_id, physical_id: physical_id)
             result = @registry.activate_instance_snapshot(
               publisher_token: publisher_token, instance_key: key, offerings: offerings,
               sequence: sequence, probe_token: probe_token
@@ -44,26 +50,26 @@ module Legion
             sync_applied(key, result)
           end
 
-          def replace_instance_snapshot(instance_id:, publisher_token:, offerings:, sequence:)
-            key = instance_key(instance_id)
+          def replace_instance_snapshot(instance_id:, publisher_token:, offerings:, sequence:, physical_id: nil)
+            key = instance_key(instance_id: instance_id, physical_id: physical_id)
             result = @registry.replace_instance_snapshot(
               publisher_token: publisher_token, instance_key: key, offerings: offerings, sequence: sequence
             )
             sync_applied(key, result)
           end
 
-          def readiness_succeeded(instance_id:, probe_token:)
-            key = instance_key(instance_id)
+          def readiness_succeeded(instance_id:, probe_token:, physical_id: nil)
+            key = instance_key(instance_id: instance_id, physical_id: physical_id)
             sync_applied(key, @registry.readiness_succeeded(instance_key: key, probe_token: probe_token))
           end
 
-          def readiness_failed(instance_id:, probe_token:, reason:)
-            key = instance_key(instance_id)
+          def readiness_failed(instance_id:, probe_token:, reason:, physical_id: nil)
+            key = instance_key(instance_id: instance_id, physical_id: physical_id)
             sync_applied(key, @registry.readiness_failed(instance_key: key, probe_token: probe_token, reason: reason))
           end
 
-          def remove_instance(instance_id:, publisher_token:)
-            key = instance_key(instance_id)
+          def remove_instance(instance_id:, publisher_token:, physical_id: nil)
+            key = instance_key(instance_id: instance_id, physical_id: physical_id)
             sync_applied(key, @registry.remove_instance(instance_key: key, publisher_token: publisher_token))
           end
 
@@ -73,8 +79,8 @@ module Legion
 
           private
 
-          def instance_key(instance_id)
-            Identity::InstanceKey.new(provider_family: @provider_family, instance_id: instance_id)
+          def instance_key(instance_id:, physical_id: nil)
+            Identity::InstanceKey.new(provider_family: @provider_family, instance_id: instance_id, physical_id: physical_id)
           end
 
           def sync_applied(instance_key, result)

data/lib/legion/extensions/llm/inventory/records.rb

@@ -42,9 +42,16 @@ module Legion
 
           def sanitized_reason(value:, field:, max_bytes: 1024)
             raise Errors::ValidationError, "#{field} must be a String" unless value.is_a?(::String)
-            raise Errors::ValidationError, "#{field} is not valid UTF-8" unless valid_utf8?(value)
 
-            trimmed = value.strip
+            # Coerce any source encoding to valid UTF-8 rather than raising: provider
+            # error messages can be ASCII-8BIT/binary (raw response bodies, Ruby kernel
+            # error messages). A reason is diagnostic text, not operator input to reject —
+            # raising here would mask the real dispatch error as an unclassifiable 500 and
+            # defeat fail-forward. Undecodable bytes are replaced.
+            coerced = value.dup.force_encoding(::Encoding::UTF_8)
+            coerced = coerced.scrub('?') unless coerced.valid_encoding?
+
+            trimmed = coerced.strip
             raise Errors::ValidationError, "#{field} must not be empty" if trimmed.empty?
             raise Errors::ValidationError, "#{field} exceeds #{max_bytes} UTF-8 bytes" if trimmed.bytesize > max_bytes
 

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

@@ -580,17 +580,15 @@ module Legion
           }
         end
 
-        # Resolve a single policy value with instance > provider > global precedence.
+        # Resolve a single policy value with the shared cascade
+        # (SettingsCascade: instance > provider, model leg skipped — no model
+        # exists at policy-build time) plus the legacy global
+        # extensions.llm.<key> leg. Empty values fall through.
         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)
+          value = SettingsCascade.resolve_value(provider_conf: provider_conf, instance_cfg: cfg, key: key)
+          return value unless value.nil?
 
-          # 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 = {} unless global_conf.is_a?(::Hash)
           global_conf[key] || global_conf[key.to_s]
         end
 
@@ -803,11 +801,11 @@ module Legion
         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)
+          SettingsCascade.merge_model_scopes(
+            provider_conf: provider_capability_config,
+            instance_cfg: config.respond_to?(:to_h) ? config.to_h : {},
+            model: model_id
+          )
         rescue StandardError => e
           handle_exception(e, level: :warn, handled: true, operation: "#{slug}.model_capability_config")
           {}
@@ -864,21 +862,6 @@ module Legion
           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 }]

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # The shared 3-level settings cascade: provider -> instance -> model,
+      # most-specific-first. Single home for resolving operator config
+      # (enable_* overrides, weight, preferred_min/max_context_tokens,
+      # model_whitelist/blacklist, ...) for a
+      # (provider_family, instance, model, key) request.
+      #
+      # `instance` is the operator's CONFIG NAME — the same identity
+      # Identity::InstanceKey#instance_id and the router key settings lookups
+      # by — never a derived host:port/credential value.
+      #
+      # Lookup order (first meaningful value wins):
+      #   1. model:    extensions.llm.<provider>.instances.<instance>.models.<model>.<key>
+      #                then extensions.llm.<provider>.models.<model>.<key>
+      #   2. instance: extensions.llm.<provider>.instances.<instance>.<key>
+      #   3. provider: extensions.llm.<provider>.<key>
+      #
+      # Empty values (nil, blank String, empty Array) never resolve; the
+      # cascade falls through to the next scope and returns nil when no scope
+      # carries a meaningful value.
+      #
+      # The cascade READS config only. It never publishes evidence: config and
+      # override sources remain unknown-only (Taxonomies::
+      # UNKNOWN_ONLY_EVIDENCE_SOURCES), and enable_* overrides are consumed
+      # router-side, not published as capability evidence.
+      module SettingsCascade
+        module_function
+
+        # Resolve `key` for (provider_family, instance, model) from the live
+        # Legion::Settings[:extensions][:llm][<provider>] path.
+        def resolve(provider_family:, instance:, key:, model: nil)
+          text_name!(provider_family, :provider_family)
+          text_name!(instance, :instance)
+          text_name!(key, :key)
+          text_name!(model, :model) if model
+
+          llm_conf = Legion::Settings.dig(:extensions, :llm)
+          resolve_from(llm_conf: llm_conf, provider_family: provider_family, instance: instance, key: key, model: model)
+        end
+
+        # Resolve against a pre-fetched extensions.llm subtree (plain Hash),
+        # e.g. a router settings snapshot. Same cascade as .resolve.
+        def resolve_from(llm_conf:, provider_family:, instance:, key:, model: nil)
+          text_name!(provider_family, :provider_family)
+          text_name!(instance, :instance)
+          text_name!(key, :key)
+
+          provider_conf = lookup(llm_conf, provider_family)
+          instances = lookup(provider_conf, :instances)
+          instance_cfg = lookup(instances, instance)
+          resolve_value(provider_conf: provider_conf, instance_cfg: instance_cfg, key: key, model: model)
+        end
+
+        # The pure 3-level cascade over pre-fetched scope hashes:
+        # model scopes (instance-scoped first, then provider-scoped) > instance
+        # > provider. `model: nil` skips the model leg. Returns the first
+        # meaningful value or nil.
+        def resolve_value(provider_conf:, instance_cfg:, key:, model: nil)
+          text_name!(key, :key)
+          text_name!(model, :model) if model
+
+          scopes = []
+          scopes << model_scope(instance_cfg, model) if model
+          scopes << model_scope(provider_conf, model) if model
+          scopes << instance_cfg
+          scopes << provider_conf
+
+          scopes.each do |scope|
+            value = lookup(scope, key)
+            return value if meaningful?(value)
+          end
+
+          nil
+        end
+
+        # The merged model-scope config hash for one model: the provider's
+        # models.<model> entry with the instance's models.<model> entry
+        # overriding it (the merge the capability feeders use).
+        def merge_model_scopes(provider_conf:, instance_cfg:, model:)
+          text_name!(model, :model)
+
+          model_scope(provider_conf, model).merge(model_scope(instance_cfg, model))
+        end
+
+        def model_scope(scope_conf, model)
+          models = lookup(scope_conf, :models)
+          return {} unless models.is_a?(::Hash)
+
+          entry = lookup(models, model)
+          entry.is_a?(::Hash) ? entry : {}
+        end
+
+        def meaningful?(value)
+          !value.nil? && !value.to_s.empty? && (!value.is_a?(::Array) || value.any?)
+        end
+
+        # Tries the name as-given, as a Symbol, then as a String, preserving
+        # meaningful falsy values (false, 0) when the key is present.
+        def lookup(scope, name)
+          return nil unless scope.is_a?(::Hash)
+
+          return scope[name] if scope.key?(name)
+          return scope[name.to_sym] if scope.key?(name.to_sym)
+
+          scope[name.to_s]
+        end
+
+        def text_name!(name, field)
+          return if name.is_a?(::String) || name.is_a?(::Symbol)
+
+          raise ::ArgumentError, "#{field} must be a String or Symbol"
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.7.0'
+      VERSION = '0.7.2'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -45,6 +45,9 @@ module Legion
       # --- Capability resolution policy (no internal deps) ---
       require_relative 'llm/capability_policy'
 
+      # --- Shared 3-level settings cascade (provider -> instance -> model) ---
+      require_relative 'llm/settings_cascade'
+
       # --- SSOT v3 runtime contract (process-local; no legion-llm/LegionIO/transport/db/timer) ---
       require_relative 'llm/inventory/errors'
       require_relative 'llm/inventory/immutable_value'

data/spec/legion/extensions/llm/canonical/message_spec.rb

@@ -106,6 +106,30 @@ RSpec.describe Legion::Extensions::Llm::Canonical::Message do
       expect(msg.content).to eq('hello')
     end
 
+    it 'drops the transport-only :cache_control key instead of raising ArgumentError' do
+      # Regression guard (root cause B): the prompt-cache step injects :cache_control
+      # onto every >=2-message request. from_hash previously did build(**h) with the
+      # whole hash, raising ArgumentError 'unknown keyword: :cache_control' before HTTP.
+      # It now projects onto the known member keys, so the transport-only key is dropped.
+      expect do
+        described_class.from_hash(
+          role: 'user',
+          content: 'hi',
+          cache_control: { type: 'ephemeral' }
+        )
+      end.not_to raise_error
+
+      msg = described_class.from_hash(
+        role: 'user',
+        content: 'hi',
+        cache_control: { type: 'ephemeral' }
+      )
+
+      expect(msg).to be_a(described_class)
+      expect(msg.role).to eq(:user)
+      expect(msg.text).to eq('hi')
+    end
+
     it 'returns nil for nil source' do
       expect(described_class.from_hash(nil)).to be_nil
     end

data/spec/legion/extensions/llm/conformance/fixtures/canonical_params_mapping_request.json

@@ -1,5 +1,6 @@
 {
   "id": "req_params_mapping_001",
+  "metadata": { "model": "test-fixture-model" },
   "messages": [
     {
       "role": "user",

data/spec/legion/extensions/llm/conformance/fixtures/canonical_simple_text_request.json

@@ -1,5 +1,6 @@
 {
   "id": "req_simple_text_001",
+  "metadata": { "model": "test-fixture-model" },
   "messages": [
     {
       "role": "user",

data/spec/legion/extensions/llm/conformance/fixtures/canonical_system_prompt_request.json

@@ -1,5 +1,6 @@
 {
   "id": "req_system_prompt_001",
+  "metadata": { "model": "test-fixture-model" },
   "system": "You are a helpful assistant that always responds in haiku form.",
   "messages": [
     {

data/spec/legion/extensions/llm/conformance/fixtures/canonical_thinking_request.json

@@ -1,5 +1,6 @@
 {
   "id": "req_thinking_001",
+  "metadata": { "model": "test-fixture-model" },
   "messages": [
     {
       "role": "user",

data/spec/legion/extensions/llm/conformance/fixtures/canonical_tool_results_continuation_request.json

@@ -1,6 +1,7 @@
 {
   "description": "Full multi-turn history: mixed client/server tool calls + thinking block per G4",
   "id": "req_tool_continuation_001",
+  "metadata": { "model": "test-fixture-model" },
   "system": "You are a helpful assistant.",
   "messages": [
     {

data/spec/legion/extensions/llm/conformance/fixtures/canonical_tools_request.json

@@ -1,5 +1,6 @@
 {
   "id": "req_tools_001",
+  "metadata": { "model": "test-fixture-model" },
   "messages": [
     {
       "role": "user",

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

@@ -92,6 +92,19 @@ RSpec.describe Legion::Extensions::Llm::Inventory::Evidence do
           .not_to raise_error
       end
     end
+
+    it 'never lets config/override sources carry :supported (enable_* is consumed router-side, not published)' do
+      %i[model_override instance_override provider_override].each do |source|
+        expect { capability_evidence.new(capability: :tools, status: :supported, source: source) }
+          .to raise_error(errors::ValidationError)
+        expect { capability_evidence.new(capability: :thinking, status: :supported, source: source) }
+          .to raise_error(errors::ValidationError)
+        expect { operation_evidence.new(operation: :chat, status: :supported, source: source) }
+          .to raise_error(errors::ValidationError)
+        expect { capability_evidence.new(capability: :tools, status: :unknown, source: source) }
+          .not_to raise_error
+      end
+    end
   end
 
   describe 'ValueEvidence' do

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

@@ -183,9 +183,9 @@ RSpec.describe Legion::Extensions::Llm::Inventory::Identity do
       expect(key.instance_id).to eq('Prod:EastUS')
     end
 
-    it 'exposes to_h with the two fields' do
+    it 'exposes to_h with the three fields (physical_id nil by default)' do
       key = instance_key_class.new(provider_family: :vllm, instance_id: 'h200')
-      expect(key.to_h).to eq(provider_family: :vllm, instance_id: 'h200')
+      expect(key.to_h).to eq(provider_family: :vllm, instance_id: 'h200', physical_id: nil)
     end
 
     it 'is value-equal for equal normalized fields' do
@@ -213,6 +213,59 @@ RSpec.describe Legion::Extensions::Llm::Inventory::Identity do
       expect { instance_key_class.new(provider_family: 'vllm', instance_id: nil) }
         .to raise_error(errors::ValidationError)
     end
+
+    it 'keeps the two-argument constructor working (physical_id defaults to nil)' do
+      key = instance_key_class.new(provider_family: :vllm, instance_id: 'apollo')
+      expect(key.physical_id).to be_nil
+    end
+
+    describe 'physical_id (secondary, not identity)' do
+      it 'normalizes like identity text: trims, NFC, frozen String' do
+        key = instance_key_class.new(provider_family: :vllm, instance_id: 'apollo', physical_id: '  10.0.0.1:8000/ak:abc123 ')
+        expect(key.physical_id).to eq('10.0.0.1:8000/ak:abc123')
+        expect(key.physical_id).to be_frozen
+      end
+
+      it 'preserves the physical id for diagnostics while identity stays the config name' do
+        key = instance_key_class.new(
+          provider_family: :vllm, instance_id: 'apollo', physical_id: '10.0.0.1:8000/ak:abc123'
+        )
+        expect(key.instance_id).to eq('apollo')
+        expect(key.physical_id).to eq('10.0.0.1:8000/ak:abc123')
+      end
+
+      it 'excludes physical_id from equality and hashing' do
+        bare = instance_key_class.new(provider_family: :vllm, instance_id: 'apollo')
+        with_physical = instance_key_class.new(
+          provider_family: :vllm, instance_id: 'apollo', physical_id: '10.0.0.1:8000/ak:abc123'
+        )
+        other_physical = instance_key_class.new(
+          provider_family: :vllm, instance_id: 'apollo', physical_id: '10.0.0.9:9000'
+        )
+        expect(bare).to eq(with_physical)
+        expect(bare.hash).to eq(with_physical.hash)
+        expect(with_physical).to eq(other_physical)
+        expect({ bare => :found }[with_physical]).to eq(:found)
+      end
+
+      it 'does not reserve "default" for physical_id (only instance_id is reserved)' do
+        key = instance_key_class.new(provider_family: :vllm, instance_id: 'apollo', physical_id: 'default')
+        expect(key.physical_id).to eq('default')
+      end
+
+      it 'rejects a blank or non-text physical_id' do
+        expect { instance_key_class.new(provider_family: 'vllm', instance_id: 'x', physical_id: '   ') }
+          .to raise_error(errors::ValidationError)
+        expect { instance_key_class.new(provider_family: 'vllm', instance_id: 'x', physical_id: 5) }
+          .to raise_error(errors::ValidationError)
+      end
+
+      it 'still distinguishes distinct config names on the same physical endpoint' do
+        apollo = instance_key_class.new(provider_family: :ollama, instance_id: 'apollo', physical_id: 'localhost:11434')
+        apollo_embed = instance_key_class.new(provider_family: :ollama, instance_id: 'apollo-embed', physical_id: 'localhost:11434')
+        expect(apollo).not_to eq(apollo_embed)
+      end
+    end
   end
 
   describe 'public surface' do

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

@@ -101,4 +101,44 @@ RSpec.describe Legion::Extensions::Llm::Inventory::Publisher do
       expect(result).to be_a(inventory::PublisherToken)
     end
   end
+
+  describe 'secondary physical_id' do
+    it 'carries the physical id on the committed key while identity stays the config name' do
+      token = plain_publisher.claim_instance(
+        instance_id: 'h200', callable: fake_callable,
+        probe_request_handle: probe_coordinator(instance_key), physical_id: '10.0.0.1:8000/ak:abc123'
+      )
+      probe = plain_publisher.readiness_probe_started(instance_id: 'h200', publisher_token: token)
+      plain_publisher.activate_instance_snapshot(
+        instance_id: 'h200', publisher_token: token, offerings: drafts, sequence: 0, probe_token: probe
+      )
+
+      keyed_with_physical = inventory::Identity::InstanceKey.new(
+        provider_family: 'vllm', instance_id: 'h200', physical_id: '10.0.0.1:8000/ak:abc123'
+      )
+      record = plain_publisher.snapshot.instance(instance_key: keyed_with_physical)
+      expect(record).not_to be_nil
+      expect(record.instance_key.physical_id).to eq('10.0.0.1:8000/ak:abc123')
+
+      # Identity lookup without the physical id finds the same committed instance.
+      expect(plain_publisher.snapshot.instance(instance_key: instance_key)).to eq(record)
+    end
+
+    it 'replaces the same scope when the physical id changes for the same config name' do
+      old_token = plain_publisher.claim_instance(
+        instance_id: 'h200', callable: fake_callable,
+        probe_request_handle: probe_coordinator(instance_key), physical_id: '10.0.0.1:8000/ak:abc123'
+      )
+      new_token = plain_publisher.claim_instance(
+        instance_id: 'h200', callable: fake_callable,
+        probe_request_handle: probe_coordinator(instance_key), physical_id: '10.0.0.9:9000'
+      )
+
+      # The old publisher is superseded on the SAME scope (no parallel scope).
+      expect { plain_publisher.readiness_probe_started(instance_id: 'h200', publisher_token: old_token) }
+        .to raise_error(inventory::Errors::FencedPublisherError)
+      expect(plain_publisher.readiness_probe_started(instance_id: 'h200', publisher_token: new_token))
+        .to be_a(inventory::ProbeToken)
+    end
+  end
 end

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

@@ -56,4 +56,18 @@ RSpec.describe Legion::Extensions::Llm::Routing::ProviderOutcome 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/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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.2
 platform: ruby
 authors:
 - LegionIO
@@ -184,14 +184,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.14
+        version: 1.4.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.14
+        version: 1.4.2
 - !ruby/object:Gem::Dependency
   name: legion-transport
   requirement: !ruby/object:Gem::Requirement
@@ -337,6 +337,7 @@ files:
 - lib/legion/extensions/llm/routing/provider_outcome.rb
 - lib/legion/extensions/llm/routing/records.rb
 - lib/legion/extensions/llm/routing/registry_event.rb
+- lib/legion/extensions/llm/settings_cascade.rb
 - lib/legion/extensions/llm/stop_reason_mapping.rb
 - lib/legion/extensions/llm/stream_accumulator.rb
 - lib/legion/extensions/llm/streaming.rb
@@ -457,6 +458,7 @@ files:
 - spec/legion/extensions/llm/routing/provider_outcome_spec.rb
 - spec/legion/extensions/llm/routing/records_spec.rb
 - spec/legion/extensions/llm/routing/registry_event_spec.rb
+- spec/legion/extensions/llm/settings_cascade_spec.rb
 - spec/legion/extensions/llm/stop_reason_mapping_spec.rb
 - spec/legion/extensions/llm/stream_accumulator_spec.rb
 - spec/legion/extensions/llm/streaming_spec.rb