legion-llm 0.16.3 → 0.16.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c593f0ce469cb6391a8aecfea4bbccfb99220e598616e980bc005594fe789972
-  data.tar.gz: 2cb436d417122b94e0aa9eb02775aeee25047bf94ba7cb03ff8bf73f6677787f
+  metadata.gz: ff0c6b5e1aff591b55afb3776a7d14fc8c6fc607bcc5836b0c2a3ffbd31d4e83
+  data.tar.gz: 4f2e3d428bded9896ce9a4eb1044fc65e7f2025ec5116aba2bd3bdf1a5a94077
 SHA512:
-  metadata.gz: 2cb61a834758040085f1f8479119e1e36e3b77b7145fc1ee42b900454993f2356cac77ad4cd54898ded97380ae66bf905487e2ed2c26bf27a43cdf0f598ce6a7
-  data.tar.gz: 0ec4deffe1350de416f2f3f9366ebe97d20ac32154f76d25e603767b089e9155ed7896cb84ed43ceeb8306211318494c78ff8e3e8f58d0189b089b5db9e6d0d5
+  metadata.gz: 83e30aa5a9b7f2608b52159b252a7481c44909537e3643c03f1981a6b4eb5926a9642684444ea8e3b61bb0b628e03bb5e89ffcf0d51d2da077f326d7041f8029
+  data.tar.gz: 350b3cda23fcd149f9b14b6a11cefb567ab9a3b4b2ca1f2818d9991d8bcf5968156349519a10254e6ea7f7a92e89361fc7de7c6a5f14be28ed06382031b05aad

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Legion LLM Changelog
 
+## [0.16.8] - 2026-08-19
+
+### Fixed
+- **Routing consumes the SSOT lane's write-time weight.** The stateless ranker reads the immutable 100-based `weight_inputs`/`base_weight` pair published on `LaneRecord`; request-time settings recomputation and the dormant tier-component substitution are removed.
+- **Zero-weight disable remains explicit.** Any zero stored component disables the lane before ranking, while health remains the binary availability axis.
+- **Exact fleet streaming preserves the selected operation.** SSOT fleet dispatch now sources `operation` from the immutable selection, verifies it against the bound lane before envelope construction, and signs `stream_chat` through to the worker's exact stream callable instead of silently executing the chat lane.
+
+## [0.16.7] - 2026-08-19
+
+### Fixed
+- **Preferred-context bands now order without excluding.** Routing ranks in-band lanes first, then ranks every remaining ready lane when no band matches. Out-of-band lanes are never dropped, while release-bar in-band steering remains intact.
+
+## [0.16.6] - 2026-08-19
+
+### Fixed
+- **Daemon faults stay terminal.** `NoMethodError`, `ArgumentError`, `NotImplementedError`, and `TypeError` are never laundered into retryable provider outcomes; caught daemon faults re-raise raw with the original backtrace.
+- **Lease lifecycle parity across sync and stream.** Retired or disposed callable handles classify as `instance_unavailable`, trigger the existing exact-instance transition/probe behavior, and retry a different eligible lane. Streaming preflight uses an explicit bounded loop and rejects before headers when the attempt budget is exhausted.
+
+## [0.16.5] - 2026-08-19
+
+### Fixed
+- **Shared SSOT dispatch-boundary contract.** Direct and fleet requests now project only provider-callable contract keys, fold the authoritative system prompt into canonical messages exactly once, and move non-contract generation parameters under `params`. Legacy/non-SSOT calls retain their original messages and options.
+- **Signed fleet exact execution.** SSOT fleet envelopes carry and sign `execution_contract: exact_offering_v1` plus a validated nonempty `offering_id`; both dispatcher and independently callable token issuer reject unknown markers instead of silently downgrading to legacy execution. Daemon-only offering metadata never crosses the provider boundary.
+
+## [0.16.4] - 2026-08-19
+
+### Changed
+- **Human-readable SSOT routing identities.** Ranked, selected, failed-attempt, streaming preflight, and streaming failover decision logs now carry the Inventory five-tuple (`tier:provider:instance:type:model`) instead of opaque `lane:v1:` hashes. StreamAssembler preserves historically accepted public lane inputs while redacting incomplete or malformed identities as `lane_identity_missing=true`; failover-chain state is unchanged.
+- **`lex-llm >= 0.7.4` floor.** Routing logs consume the shared authoritative operation-to-lane-type mapping rather than maintaining a daemon-local copy.
+
 ## [0.16.3] - 2026-08-17
 
 ### Changed

data/legion-llm.gemspec

@@ -38,7 +38,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-settings', '>= 1.4.2'
   spec.add_dependency 'legion-transport', '>= 1.4.14'
   spec.add_dependency 'lex-knowledge'
-  spec.add_dependency 'lex-llm', '>= 0.7.0'
+  spec.add_dependency 'lex-llm', '>= 0.7.5'
   spec.add_dependency 'pdf-reader'
   spec.add_dependency 'sinatra-contrib', '>= 2.0'
   spec.add_dependency 'tzinfo', '>= 2.0'

data/lib/legion/llm/api/stream_assembler.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'legion/logging/helper'
+require 'legion/extensions/llm/taxonomies'
 require 'legion/llm/api/client_translators/shared_extractors'
 
 module Legion
@@ -246,9 +247,14 @@ module Legion
         def provider_failover_pending!(from:, **)
           return if @closed
 
-          from_id = from.is_a?(Hash) ? from[:id] : from.to_s
-          log.warn('[llm][stream_assembler] action=provider_failover_pending ' \
-                   "from=#{from_id} request_id=#{@request_id}")
+          identity = lane_identity(from)
+          if identity
+            log.warn('[llm][stream_assembler] action=provider_failover_pending ' \
+                     "from=#{identity} request_id=#{@request_id}")
+          else
+            log.warn('[llm][stream_assembler] action=provider_failover_pending ' \
+                     "lane_identity_missing=true request_id=#{@request_id}")
+          end
           # Clear the partial canonical buffer — partial responses can't cross providers
           # (thinking strip, context invalidation). The next provider starts fresh.
           close_thinking_block if @thinking_block_open
@@ -272,8 +278,14 @@ module Legion
 
           @current_lane = lane
           @failover_chain << (lane.is_a?(Hash) ? lane[:id] : lane.to_s)
-          log.info("[llm][stream_assembler] action=begin_dispatch lane=#{lane.is_a?(Hash) ? lane[:id] : lane} " \
-                   "request_id=#{@request_id}")
+          identity = lane_identity(lane)
+          if identity
+            log.info("[llm][stream_assembler] action=begin_dispatch lane=#{identity} " \
+                     "request_id=#{@request_id}")
+          else
+            log.warn('[llm][stream_assembler] action=begin_dispatch ' \
+                     "lane_identity_missing=true request_id=#{@request_id}")
+          end
         end
 
         def safe_replay_snapshot
@@ -303,6 +315,24 @@ module Legion
 
         private
 
+        # Returns the exact five-tuple for complete internal lane hashes.
+        # Opaque or partial public values retain control behavior but are never
+        # echoed into logs.
+        def lane_identity(lane)
+          keys = %i[tier provider_family instance_id type model]
+          return unless lane.is_a?(Hash)
+          return unless keys.all? do |key|
+            value = lane[key]
+            next false unless lane.key?(key) && (value.is_a?(String) || value.is_a?(Symbol))
+
+            text = value.to_s
+            text.valid_encoding? && !text.match?(/[[:cntrl:]]/) && !text.strip.empty?
+          end
+          return unless Legion::Extensions::Llm::Taxonomies::TYPES.include?(lane[:type].to_sym)
+
+          "#{lane[:tier]}:#{lane[:provider_family]}:#{lane[:instance_id]}:#{lane[:type]}:#{lane[:model]}"
+        end
+
         # G30 / D-F: emit x-legion-failover-* debug trailers after on_done.
         # Only fires when failover actually happened (@failover_chain has markers).
         # Trailers are response metadata, not SSE events — no wire-level event emitted.

data/lib/legion/llm/call/selection_dispatch.rb

@@ -58,17 +58,29 @@ module Legion
           lease = dispatch_lease || Legion::Extensions::Llm::Inventory::Registry.acquire(
             callable_handle: selection.callable_handle
           )
+          log.debug("[llm][selection_dispatch] action=lease_acquired handle=#{selection.callable_handle.handle_id} " \
+                    "lease=#{lease.lease_id}")
           callable = lease.callable
 
           begin
             Result.success(value: invocation.call(callable))
           rescue StandardError => e
+            log.warn("[llm][selection_dispatch] action=dispatch_failed class=#{e.class.name} " \
+                     "message=#{e.message.to_s[0, 200]}")
+            raise if daemon_fault?(e)
+
             Result.failure(outcome: normalize(callable: callable, error: e))
           ensure
             lease.release if owned_lease && !lease.released?
           end
         end
 
+        def self.daemon_fault?(error)
+          error.is_a?(::NoMethodError) || error.is_a?(::ArgumentError) ||
+            error.is_a?(::NotImplementedError) || error.is_a?(::TypeError)
+        end
+        private_class_method :daemon_fault?
+
         # Normalize a provider error through the exact callable's Phase 1
         # normalizer. A normalizer that raises or returns the wrong type is a
         # programming failure — report and re-raise, never a silent success.
@@ -78,6 +90,8 @@ module Legion
             raise TypeError,
                   "normalize_dispatch_error returned #{outcome.class}, expected ProviderOutcome"
           end
+          log.warn("[llm][selection_dispatch] action=dispatch_normalized kind=#{outcome.kind} " \
+                   "reason=#{outcome.reason.to_s[0, 200]}")
           outcome
         rescue StandardError => e
           # Log the ORIGINAL dispatch error too — a normalizer that raises must never
@@ -87,6 +101,8 @@ module Legion
                               handled: false, lane_id: nil,
                               original_error_class: error.class.name,
                               original_error_message: error.message.to_s.dup.force_encoding(::Encoding::UTF_8).scrub('?')[0, 512])
+          log.warn("[llm][selection_dispatch] action=normalizer_failed class=#{e.class.name} " \
+                   "message=#{e.message.to_s[0, 200]}")
           raise
         end
         private_class_method :normalize

data/lib/legion/llm/fleet/dispatcher.rb

@@ -16,9 +16,10 @@ module Legion
         extend Legion::Logging::Helper
 
         ENVELOPE_KEYS = %i[
-          app_id caller correlation_id expires_at idempotency_key identity message_context operation
-          model priority protocol_version provider provider_instance reply_to request_id routing_key
-          signed_token timeout timeout_seconds trace_context ttl
+          app_id caller correlation_id expires_at execution_contract idempotency_key identity
+          message_context offering_id operation model priority protocol_version provider
+          provider_instance reply_to request_id routing_key signed_token timeout timeout_seconds
+          trace_context ttl
         ].freeze
         LEGACY_FIELDS = %i[schema_version request_type fleet_correlation_id].freeze
 
@@ -96,6 +97,18 @@ module Legion
             expires_at:        (Time.now.utc + timeout).iso8601,
             ttl:               effective_ttl(request_opts, timeout)
           }
+          execution_contract = fetch_option(request_opts, :execution_contract)
+          unless execution_contract.nil?
+            unless execution_contract == ::Legion::Extensions::Llm::Fleet::Protocol::EXACT_EXECUTION_CONTRACT
+              raise ArgumentError, "unknown fleet execution_contract marker: #{execution_contract.inspect}"
+            end
+
+            offering_id = fetch_option(request_opts, :offering_id)
+            raise ArgumentError, 'exact execution contract requires a nonempty String offering_id' unless offering_id.is_a?(String) && !offering_id.strip.empty?
+
+            envelope[:execution_contract] = execution_contract
+            envelope[:offering_id] = offering_id
+          end
           envelope[:signed_token] = dispatch_auth_required? ? TokenIssuer.issue(envelope) : 'unsigned'
           envelope
         end

data/lib/legion/llm/fleet/token_issuer.rb

@@ -3,6 +3,7 @@
 require 'securerandom'
 require 'time'
 
+require 'legion/extensions/llm/fleet/protocol'
 require 'legion/extensions/llm/fleet/token_error'
 
 module Legion
@@ -60,6 +61,18 @@ module Legion
 
             claims[key] = value
           end
+          execution_contract = payload[:execution_contract]
+          unless execution_contract.nil?
+            unless execution_contract == ::Legion::Extensions::Llm::Fleet::Protocol::EXACT_EXECUTION_CONTRACT
+              raise TokenError, "unknown fleet execution_contract marker: #{execution_contract.inspect}"
+            end
+
+            offering_id = payload[:offering_id]
+            raise TokenError, 'missing token claim source: nonempty String offering_id (exact execution marker present)' unless offering_id.is_a?(String) && !offering_id.strip.empty?
+
+            claims[:execution_contract] = execution_contract
+            claims[:offering_id] = offering_id
+          end
           claims
         end
 

data/lib/legion/llm/inference/executor/escalation.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'faraday'
+require 'legion/extensions/llm/inventory/errors'
+require 'legion/extensions/llm/taxonomies'
 
 module Legion
   module LLM
@@ -58,9 +60,21 @@ module Legion
               populate_ssot_v3_resolved_state(attempt)
               result = ssot_v3_execute_attempt
               action = @routing_session.classify(dispatch_result: result, attempt_context: attempt)
+              unless action.disposition == :success
+                lane = attempt.lane
+                log.warn("[llm][executor] action=ssot_v3_attempt_failed attempt=#{attempt.attempt_number} " \
+                         "lane=#{lane.tier}:#{lane.provider_family}:#{lane.instance_id}:#{lane_type_for(lane.operation)}:#{lane.model} " \
+                         "provider=#{@resolved_provider} " \
+                         "instance=#{@resolved_instance} model=#{@resolved_model} " \
+                         "outcome_kind=#{result.outcome.kind} outcome_reason=#{result.outcome.reason.to_s[0, 200]} " \
+                         "disposition=#{action.disposition}")
+              end
               return if action.disposition == :success
               raise Legion::LLM::Errors::RoutingRejected.new(rejection: action.rejection) if action.disposition == :terminal
             end
+            log.warn('[llm][executor] action=ssot_v3_attempts_exhausted kind=attempts_exhausted ' \
+                     "reason=maximum attempts (#{@routing_requirements.maximum_attempts}) reached " \
+                     "http_status=503 generation=#{Legion::Extensions::Llm::Inventory::Registry.snapshot.generation}")
             raise Legion::LLM::Errors::RoutingRejected.new(rejection: attempts_exhausted_rejection)
           ensure
             @current_attempt_context = nil
@@ -73,11 +87,24 @@ module Legion
           def ssot_v3_execute_attempt
             execute_provider_request
             Legion::LLM::Call::SelectionDispatch::Result.success(value: @raw_response)
+          rescue Legion::Extensions::Llm::Inventory::Errors::StaleCallableError,
+                 Legion::Extensions::Llm::Inventory::Errors::CallableDisposedError => e
+            log.warn("[llm][executor] action=ssot_v3_stale_callable class=#{e.class.name} " \
+                     "message=#{e.message.to_s[0, 200]}")
+            Legion::LLM::Call::SelectionDispatch::Result.failure(
+              outcome: Legion::Extensions::Llm::Routing::ProviderOutcome.new(
+                kind: :instance_unavailable, reason: e.class.name
+              )
+            )
           rescue StandardError => e
-            raise e if non_provider_failure?(e)
+            raise if non_provider_failure?(e)
 
             outcome = @last_ssot_dispatch_outcome
             @last_ssot_dispatch_outcome = nil
+            if outcome.nil?
+              log.warn("[llm][executor] action=ssot_v3_unnormalized_error class=#{e.class.name} " \
+                       "message=#{e.message.to_s[0, 200]}")
+            end
             outcome ||= Legion::Extensions::Llm::Routing::ProviderOutcome.new(
               kind: :provider_error, reason: e.class.name.to_s
             )
@@ -104,19 +131,42 @@ module Legion
           # never an SSE server_error. Always selects (single engine) — an empty
           # Registry yields a typed Rejection, never a legacy fallback.
           def ssot_v3_stream_preflight
-            snap = Legion::Extensions::Llm::Inventory::Registry.snapshot
             @stream_session = Legion::LLM::Inference::RoutingSession.new(
               request: @request, requirements: @routing_requirements
             )
-            attempt_context = @stream_session.next_attempt!(snapshot: snap)
-            populate_ssot_v3_resolved_state(attempt_context)
-            @preflight_lease = Legion::Extensions::Llm::Inventory::Registry.acquire(
-              callable_handle: attempt_context.selection.callable_handle
-            )
-            lane = ssot_v3_stream_lane_hash(attempt_context)
-            log.info "[llm][executor] action=ssot_v3_stream_preflight_selected lane=#{lane[:id]} " \
-                     "provider=#{@resolved_provider} model=#{@resolved_model}"
-            lane
+            remaining = @routing_requirements.maximum_attempts
+            while remaining.positive?
+              remaining -= 1
+              snap = Legion::Extensions::Llm::Inventory::Registry.snapshot
+              attempt_context = @stream_session.next_attempt!(snapshot: snap)
+              begin
+                @preflight_lease = Legion::Extensions::Llm::Inventory::Registry.acquire(
+                  callable_handle: attempt_context.selection.callable_handle
+                )
+              rescue Legion::Extensions::Llm::Inventory::Errors::StaleCallableError,
+                     Legion::Extensions::Llm::Inventory::Errors::CallableDisposedError => e
+                log.warn('[llm][executor] action=ssot_v3_stream_preflight_stale_callable ' \
+                         "class=#{e.class.name} message=#{e.message.to_s[0, 200]}")
+                @stream_session.classify(
+                  dispatch_result: Legion::LLM::Call::SelectionDispatch::Result.failure(
+                    outcome: Legion::Extensions::Llm::Routing::ProviderOutcome.new(
+                      kind: :instance_unavailable, reason: e.class.name
+                    )
+                  ),
+                  attempt_context: attempt_context
+                )
+                next
+              end
+
+              populate_ssot_v3_resolved_state(attempt_context)
+              lane = ssot_v3_stream_lane_hash(attempt_context)
+              log.info '[llm][executor] action=ssot_v3_stream_preflight_selected ' \
+                       "lane=#{lane[:tier]}:#{lane[:provider_family]}:#{lane[:instance_id]}:#{lane[:type]}:#{lane[:model]} " \
+                       "provider=#{@resolved_provider} model=#{@resolved_model}"
+              return lane
+            end
+
+            raise Legion::LLM::Errors::RoutingRejected.new(rejection: attempts_exhausted_rejection)
           end
 
           # Lane Hash consumed by StreamAssembler (#initial_lane, #begin_dispatch_on,
@@ -124,12 +174,14 @@ module Legion
           # the failover debug trailers report real lane IDs — NOT 'unknown:pending'.
           def ssot_v3_stream_lane_hash(attempt_context)
             sel = attempt_context.selection
+            lane = attempt_context.lane
             {
               id:              sel.lane_id,
               provider_family: sel.provider_family,
               instance_id:     sel.instance_id,
               model:           sel.model,
-              tier:            attempt_context.lane.tier
+              tier:            lane.tier,
+              type:            lane_type_for(lane.operation)
             }
           end
 
@@ -192,11 +244,24 @@ module Legion
           def ssot_v3_stream_handle_failure(error:, session:, attempt_context:)
             raise error if non_provider_failure?(error)
 
-            outcome = ssot_v3_stream_failover_outcome(error)
+            outcome = if error.is_a?(Legion::Extensions::Llm::Inventory::Errors::StaleCallableError) ||
+                         error.is_a?(Legion::Extensions::Llm::Inventory::Errors::CallableDisposedError)
+                        log.warn("[llm][executor] action=ssot_v3_stream_stale_callable class=#{error.class.name} " \
+                                 "message=#{error.message.to_s[0, 200]}")
+                        Legion::Extensions::Llm::Routing::ProviderOutcome.new(
+                          kind: :instance_unavailable, reason: error.class.name
+                        )
+                      else
+                        ssot_v3_stream_failover_outcome(error)
+                      end
             action = session.classify(
               dispatch_result: Legion::LLM::Call::SelectionDispatch::Result.failure(outcome: outcome),
               attempt_context: attempt_context
             )
+            if action.disposition == :terminal
+              log.warn("[llm][executor] action=ssot_v3_stream_terminal class=#{error.class.name} " \
+                       "message=#{error.message.to_s[0, 200]} outcome_kind=#{outcome.kind}")
+            end
             raise error if action.disposition == :terminal
 
             # Preserve the existing StreamAssembler failover sequence (§19). The
@@ -210,14 +275,27 @@ module Legion
 
             snap = Legion::Extensions::Llm::Inventory::Registry.snapshot
             nxt = session.next_attempt(snapshot: snap)
+            if nxt.is_a?(Legion::Extensions::Llm::Routing::Rejection)
+              log.warn("[llm][executor] action=ssot_v3_stream_exhausted kind=#{nxt.kind} reason=#{nxt.reason.to_s[0, 200]} " \
+                       "class=#{error.class.name} message=#{error.message.to_s[0, 200]}")
+            end
             raise error if nxt.is_a?(Legion::Extensions::Llm::Routing::Rejection)
 
             @stream_observer&.begin_dispatch_on(lane: ssot_v3_stream_lane_hash(nxt))
+            next_lane = nxt.lane
+            next_identity = [
+              next_lane.tier, next_lane.provider_family, next_lane.instance_id,
+              lane_type_for(next_lane.operation), next_lane.model
+            ].join(':')
             log.warn "[llm][executor] action=ssot_v3_stream_failover from_kind=#{outcome.kind} " \
-                     "to_lane=#{nxt.selection.lane_id}"
+                     "outcome_reason=#{outcome.reason.to_s[0, 200]} to_lane=#{next_identity}"
             nxt
           end
 
+          def lane_type_for(operation)
+            Legion::Extensions::Llm::Taxonomies.lane_type_for(operation: operation)
+          end
+
           # Map a raised streaming provider error to a Phase 1 ProviderOutcome for
           # classification. The exact outcome from SelectionDispatch is preserved
           # losslessly by ssot_v3_direct_dispatch (@last_ssot_dispatch_outcome);
@@ -291,7 +369,8 @@ module Legion
           # shared daemon code — retrying on a different lane guarantees the same crash. Classified as
           # terminal: raise immediately, never retry, never trip circuits, never push to tried_lanes.
           def internal_error?(err)
-            err.is_a?(::NoMethodError) || err.is_a?(::ArgumentError) || err.is_a?(::NotImplementedError)
+            err.is_a?(::NoMethodError) || err.is_a?(::ArgumentError) ||
+              err.is_a?(::NotImplementedError) || err.is_a?(::TypeError)
           end
 
           # SSE assembly / canonical parse / translation errors originate inside LegionIO's

data/lib/legion/llm/inference/route_attempts.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
+require 'legion/extensions/llm/fleet/protocol'
+
 module Legion
   module LLM
     module Inference
       # Shared executor helpers for direct/fleet provider dispatch attempt metadata.
       module RouteAttempts
+        CONTRACT_OPTION_KEYS = %i[tools temperature params headers schema thinking tool_prefs].freeze
+        NONCONTRACT_GENERATION_KEYS = %i[top_p top_k frequency_penalty presence_penalty seed].freeze
+        private_constant :CONTRACT_OPTION_KEYS, :NONCONTRACT_GENERATION_KEYS
+
         private
 
         def fleet_dispatch?
@@ -12,13 +18,28 @@ module Legion
         end
 
         def dispatch_provider_request(capability:, operation:, messages:, stream_block: nil)
+          raw_options = native_dispatch_options
+          dispatch_messages, dispatch_options = if @current_attempt_context
+                                                  project_dispatch_arguments(
+                                                    messages: messages, options: raw_options
+                                                  )
+                                                else
+                                                  [messages, raw_options]
+                                                end
           if fleet_dispatch?
-            log.debug "[llm][route_attempts] action=dispatch path=fleet provider=#{@resolved_provider} model=#{@resolved_model} operation=#{operation}"
-            dispatch_fleet_request(operation: operation, messages: messages, stream_block: stream_block)
+            fleet_operation = ssot_v3_fleet_operation(operation)
+            log.debug "[llm][route_attempts] action=dispatch path=fleet provider=#{@resolved_provider} model=#{@resolved_model} operation=#{fleet_operation}"
+            dispatch_fleet_request(
+              operation: fleet_operation, messages: dispatch_messages,
+              dispatch_options: dispatch_options, stream_block: stream_block
+            )
           else
             log.debug "[llm][route_attempts] action=dispatch path=direct provider=#{@resolved_provider} model=#{@resolved_model} operation=#{operation}"
-            dispatch_direct_request(capability: capability, operation: operation, messages: messages,
-                                    stream_block: stream_block)
+            dispatch_direct_request(
+              capability: capability, operation: operation, messages: dispatch_messages,
+              raw_messages: messages, dispatch_options: dispatch_options,
+              raw_dispatch_options: raw_options, stream_block: stream_block
+            )
           end
         end
 
@@ -27,10 +48,10 @@ module Legion
         # The capability :responses capability is a provider wire-format detail — the canonical
         # core only knows :chat and :stream. See lex-llm-* adapters for wire-format decisions.
 
-        def dispatch_direct_request(capability:, operation:, messages:, stream_block: nil)
+        def dispatch_direct_request(capability:, operation:, messages:, raw_messages:,
+                                    dispatch_options:, raw_dispatch_options:, stream_block: nil)
           idempotency_key = next_route_idempotency_key
-          dispatch_options = native_dispatch_options
-          enforce_final_context_budget!(messages, dispatch_options)
+          enforce_final_context_budget!(raw_messages, raw_dispatch_options)
 
           if @current_attempt_context
             return ssot_v3_direct_dispatch(
@@ -128,7 +149,8 @@ module Legion
           end
         end
 
-        def dispatch_fleet_request(operation:, messages:, stream_block: nil)
+        def dispatch_fleet_request(operation:, messages:, dispatch_options:, stream_block: nil)
+          validate_ssot_v3_fleet_operation!(operation)
           idempotency_key = next_route_idempotency_key
           selected_lane = fleet_selected_lane(operation)
           log.info "[llm][route_attempts] action=fleet_dispatch provider=#{@resolved_provider} model=#{@resolved_model} lane=#{selected_lane} operation=#{operation}"
@@ -136,7 +158,9 @@ module Legion
             operation:       operation,
             routing_key:     selected_lane,
             message_context: fleet_message_context,
-            request:         fleet_dispatch_request(messages, idempotency_key)
+            request:         fleet_dispatch_request(
+              messages, idempotency_key, dispatch_options: dispatch_options
+            )
           )
           if result[:success] == false || result['success'] == false
             failure_reason = result[:error] || result['error'] || 'fleet_error'
@@ -164,6 +188,28 @@ module Legion
           normalized
         end
 
+        def ssot_v3_fleet_operation(requested_operation)
+          return requested_operation unless @current_attempt_context
+
+          selection_operation = @current_attempt_context.selection.operation
+          lane_operation = @current_attempt_context.lane.operation
+          unless selection_operation == lane_operation
+            raise ArgumentError,
+                  "SSOT fleet selection/lane operation mismatch: #{selection_operation.inspect} != #{lane_operation.inspect}"
+          end
+
+          selection_operation
+        end
+
+        def validate_ssot_v3_fleet_operation!(operation)
+          return unless @current_attempt_context
+          return if operation == @current_attempt_context.selection.operation
+
+          raise ArgumentError,
+                "SSOT fleet envelope operation mismatch: #{operation.inspect} != " \
+                "#{@current_attempt_context.selection.operation.inspect}"
+        end
+
         def enforce_final_context_budget!(messages, dispatch_options)
           context_window = final_context_window
           return unless context_window.positive?
@@ -197,7 +243,7 @@ module Legion
           (metadata[:context_window] || metadata['context_window'] || limits[:context_window]).to_i
         end
 
-        def fleet_dispatch_request(messages, idempotency_key)
+        def fleet_dispatch_request(messages, idempotency_key, dispatch_options:)
           {
             provider:          @resolved_provider,
             provider_instance: @resolved_instance || :default,
@@ -207,7 +253,46 @@ module Legion
             caller:            @request.caller,
             trace_context:     @tracing || {},
             timeout:           @request.ttl
-          }.merge(native_dispatch_options).compact
+          }.merge(dispatch_options).merge(exact_execution_envelope_fields).compact
+        end
+
+        def exact_execution_envelope_fields
+          return {} unless @current_attempt_context
+
+          raise ArgumentError, 'SSOT fleet dispatch requires a nonempty String resolved offering_id' unless @resolved_offering_id.is_a?(String) && !@resolved_offering_id.strip.empty?
+
+          {
+            execution_contract: ::Legion::Extensions::Llm::Fleet::Protocol::EXACT_EXECUTION_CONTRACT,
+            offering_id:        @resolved_offering_id
+          }
+        end
+
+        def project_dispatch_arguments(messages:, options:)
+          system_text = options[:system].to_s
+          folded = if system_text.strip.empty?
+                     messages
+                   else
+                     fold_system_into_messages(messages: messages, system: system_text)
+                   end
+          projected = options.slice(*CONTRACT_OPTION_KEYS)
+          params = projected[:params]
+          raise ArgumentError, "dispatch params must be a Hash, got #{params.class}" unless params.nil? || params.is_a?(Hash)
+
+          extras = NONCONTRACT_GENERATION_KEYS.each_with_object({}) do |key, acc|
+            acc[key] = options[key] if options.key?(key) && !options[key].nil?
+          end
+          projected[:params] = (params || {}).merge(extras) unless extras.empty?
+          [folded, projected]
+        end
+
+        def fold_system_into_messages(messages:, system:)
+          message_class = Legion::Extensions::Llm::Canonical::Message
+          first = messages.first
+          if first.is_a?(message_class) && first.role.to_s == 'system'
+            [first.with(content: system), *messages[1..]]
+          else
+            [message_class.build(role: :system, content: system), *messages]
+          end
         end
 
         def normalize_fleet_result(result)
@@ -260,6 +345,10 @@ module Legion
         end
 
         def record_route_attempt(dispatch_path:, operation:, status:, idempotency_key:, selected_lane:, failure_reason: nil)
+          log.debug "[llm][route_attempts] action=route_attempt provider=#{@resolved_provider} " \
+                    "instance=#{@resolved_instance} model=#{@resolved_model} operation=#{operation} " \
+                    "dispatch_path=#{dispatch_path} status=#{status} " \
+                    "failure_reason=#{failure_reason.to_s[0, 200] if failure_reason}"
           attempt = {
             provider:          @resolved_provider,
             provider_instance: @resolved_instance || :default,

data/lib/legion/llm/inference/routing_session.rb

@@ -72,6 +72,8 @@ module Legion
         # remove or overwrite a consumed attempt-target exclusion.
         def add_exclusion(exclusion:)
           @exclusions << exclusion
+          log.debug("[llm][routing_session] action=exclusion_added kind=#{exclusion.target_kind} " \
+                    "reason=#{exclusion.reason} target_kind_seen=#{exclusion.target_kind}")
           exclusion
         end
 
@@ -85,6 +87,8 @@ module Legion
           )
           apply_global_transition(action.global_transition) if action.global_transition
           action.exclusions.each { |ex| add_exclusion(exclusion: ex) }
+          log.debug("[llm][routing_session] action=outcome_classified kind=#{dispatch_result.outcome.kind} " \
+                    "disposition=#{action.disposition} exclusions_added=#{action.exclusions.size}")
           action
         end
 
@@ -109,6 +113,7 @@ module Legion
             target_kind: :attempt_target, target: key, reason: 'attempt_consumed',
             evidence: { attempt_number: @attempt_count }, lifetime: :request
           )
+          log.debug("[llm][routing_session] action=attempt_consumed attempt_number=#{@attempt_count} target=#{key}")
         end
 
         def apply_global_transition(transition)

data/lib/legion/llm/router/candidate_evaluator.rb

@@ -48,6 +48,15 @@ module Legion
                       "candidates=#{candidates.size} " \
                       "pub_statuses=#{publication_statuses.size} " \
                       "generation=#{snapshot.generation}")
+            log.debug('[llm][candidate_evaluator] action=evaluated_summary ' \
+                      "ready=#{candidates.count(&:ready?)} " \
+                      "not_ready=#{candidates.count { |c| !c.ready? }} " \
+                      "policy_denied=#{candidates.count { |c| !c.ready? && c.policy_state == :denied }} " \
+                      "capability_failed=#{candidates.count { |c| !c.ready? && c.capability_state != :supported }} " \
+                      "context_rejected=#{candidates.count { |c| !c.ready? && !%i[fits not_applicable].include?(c.context_state) }} " \
+                      "unavailable=#{candidates.count { |c| !c.ready? && c.availability_state == :unavailable }} " \
+                      "excluded=#{candidates.count { |c| !c.ready? && c.exclusion_state == :excluded }} " \
+                      "weight_disabled=#{candidates.count { |c| !c.ready? && c.weight_state == :disabled }}")
 
             EvaluationSet.new(
               candidates:           candidates,
@@ -109,11 +118,8 @@ module Legion
             # Step 9 — fleet contract marker when tier is :fleet
             fleet_contract_state = evaluate_fleet_contract(offering: offering)
 
-            # Step 10 — configured weight components
-            weight_state, weight_inputs = evaluate_weight(
-              lane:              lane,
-              settings_snapshot: settings_snapshot
-            )
+            # Step 10 — stored write-time weight components
+            weight_state, weight_inputs = evaluate_weight(lane: lane)
 
             # Soft sieve input for Ranker §10.1
             preferred_context_match = evaluate_preferred_context(
@@ -355,15 +361,15 @@ module Legion
             end
           end
 
-          # §9.7 step 10 — configured weight components.
+          # §9.7 step 10 — stored write-time weight components.
           # Any zero component → :disabled with nil weight_inputs.
           # All positive → :enabled with frozen weight_inputs Hash.
           # Nil lane (unsupported/unknown operation) → :disabled.
-          def evaluate_weight(lane:, settings_snapshot:)
+          def evaluate_weight(lane:)
             return [:disabled, nil] if lane.nil?
 
-            inputs = settings_snapshot.weight_inputs_for(lane: lane)
-            if inputs.values.any?(&:zero?)
+            inputs = lane.weight_inputs
+            if inputs.nil? || inputs.values.any?(&:zero?)
               [:disabled, nil]
             else
               [:enabled, inputs]

data/lib/legion/llm/router/ranker.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'digest'
+require 'legion/extensions/llm/taxonomies'
 
 module Legion
   module LLM
@@ -66,12 +67,22 @@ module Legion
           log.debug("[llm][ranker] action=rank ready_count=#{ready.size} " \
                     "seed=#{@requirements.routing_seed[0, 8]}...")
 
-          # Step 2 (§10.1): preferred-context soft sieve.
-          sieved = preferred_context_sieve(ready)
+          # Two-pass band ordering (preferred != required): pass 1 ranks the in-band
+          # lanes; pass 2 (only when pass 1 is empty) ranks everything else,
+          # band-ignoring. No lane is excluded by the band -- the band is a priority,
+          # not a filter. Only the selected pass is computed, so the ranked log lines
+          # are exactly the lanes eligible for this attempt.
+          in_band, out_of_band = band_partition(ready)
+
+          log.debug("[llm][ranker] action=preferred_band_partition ready=#{ready.size} " \
+                    "in_band=#{in_band.size} out_of_band=#{out_of_band.size}")
 
           # Steps 3–4 (§10.2 + D17): base weight, affinity, effective weight.
           # Step 5 (§10.3): rendezvous score.
-          ranked = compute_ranked(sieved)
+          # Pass 1 wins if non-empty; otherwise pass 2. Within a pass: greatest
+          # effective_weight bucket -> greatest rendezvous score -> ascending lane_id.
+          ranked = compute_ranked(in_band) if in_band.any?
+          ranked ||= compute_ranked(out_of_band)
 
           # Select the winner (greatest effective_weight bucket → greatest rendezvous
           # score → lexicographically ascending lane_id for cryptographically
@@ -85,24 +96,22 @@ module Legion
         # §10.1 Preferred-context soft sieve                                   #
         # ------------------------------------------------------------------ #
 
-        def preferred_context_sieve(ready)
-          budget     = @requirements.required_context_budget
-          with_range = ready.map { |c| [c, @settings_snapshot.preferred_context_range_for(lane: c.lane)] }
-
-          # `with_range` is an array of [candidate, range|nil] pairs. A lane with
-          # no preferred range is a generalist; a lane whose range contains the
-          # budget matches. The nil guard is folded into the match select on
-          # purpose: `with_range.compact`/`reject { |_, r| r.nil? }` would misfire
-          # (Style/CollectionCompact treats it as hash semantics) and leave nil
-          # ranges in, which then crash range_contains? with `nil[:min]`.
-          generalist = with_range.select { |_, r| r.nil? }.map(&:first)
-          matching   = with_range.select { |_, r| r && range_contains?(r, budget) }.map(&:first)
-
-          # Preferred range is soft: never makes any lane hard-ineligible.
-          return matching   unless matching.empty?
-          return generalist unless generalist.empty?
-
-          ready
+        # Partition ready candidates by preferred-band containment. A lane with no
+        # configured range is out_of_band (generalist). A lane whose range does not
+        # contain the budget is also out_of_band -- never excluded.
+        def band_partition(ready)
+          budget      = @requirements.required_context_budget
+          in_band     = []
+          out_of_band = []
+          ready.each do |candidate|
+            range = @settings_snapshot.preferred_context_range_for(lane: candidate.lane)
+            if range && range_contains?(range, budget)
+              in_band << candidate
+            else
+              out_of_band << candidate
+            end
+          end
+          [in_band, out_of_band]
         end
 
         # True when +budget+ falls within the (nil-open) range [min, max) —
@@ -118,22 +127,25 @@ module Legion
         # ------------------------------------------------------------------ #
 
         def compute_ranked(candidates)
-          # Precompute the tier boost value once; it is the same for every candidate.
-          tier_max_plus_one = @settings_snapshot.tier_weights.values.max + 1
-
           candidates.map do |candidate|
-            wi    = build_weight_inputs(candidate, tier_max_plus_one)
-            base  = wi.values.reduce(1, :*)
+            # Stored write-time scalar: the operator's tier/provider/instance/model
+            # weights are baked in by the inventory writer. The former request-time
+            # tier_preference substitution is deliberately removed: applying a tier
+            # component to the stored scalar would double-count that axis. A future
+            # request-time tier preference requires a first-class ppm-domain term.
+            base  = candidate.lane.base_weight
             ppm   = compute_preference_ppm(candidate)
             eff   = base * ppm
             score = rendezvous_score(candidate)
 
-            log.debug("[llm][ranker] action=ranked lane=#{candidate.lane.lane_id[0, 20]}... " \
+            lane = candidate.lane
+            log.debug('[llm][ranker] action=ranked ' \
+                      "lane=#{lane.tier}:#{lane.provider_family}:#{lane.instance_id}:#{lane_type_for(lane.operation)}:#{lane.model} " \
                       "base=#{base} ppm=#{ppm} eff=#{eff}")
 
             RankedCandidate.new(
               evaluation:       candidate,
-              weight_inputs:    wi,
+              weight_inputs:    candidate.lane.weight_inputs,
               base_weight:      base,
               preference_ppm:   ppm,
               effective_weight: eff,
@@ -142,20 +154,6 @@ module Legion
           end
         end
 
-        # §10.2: optionally substitute the tier weight for the preferred tier.
-        # All other components are taken verbatim from the evaluation-time snapshot.
-        def build_weight_inputs(candidate, tier_max_plus_one)
-          base_wi = candidate.weight_inputs
-          tier_w  = if @requirements.tier_preference &&
-                       candidate.lane.tier == @requirements.tier_preference
-                      tier_max_plus_one
-                    else
-                      base_wi[:tier]
-                    end
-          { tier: tier_w, provider: base_wi[:provider],
-            instance: base_wi[:instance], model_or_offering: base_wi[:model_or_offering] }.freeze
-        end
-
         # §10.2/D17: compute preference_ppm using integer floor division throughout.
         # Bounds: 500_000..1_500_000 (clamped as a belt-and-suspenders guard; the
         # input constraints guarantee the range without it).
@@ -216,7 +214,16 @@ module Legion
         def select_winner(ranked)
           max_ew = ranked.map(&:effective_weight).max
           bucket = ranked.select { |rc| rc.effective_weight == max_ew }
-          bucket.min_by { |rc| [-rc.rendezvous_score, rc.evaluation.lane.lane_id] }
+          winner = bucket.min_by { |rc| [-rc.rendezvous_score, rc.evaluation.lane.lane_id] }
+          lane = winner.evaluation.lane
+          log.debug('[llm][ranker] action=selected ' \
+                    "lane=#{lane.tier}:#{lane.provider_family}:#{lane.instance_id}:#{lane_type_for(lane.operation)}:#{lane.model} " \
+                    "eff=#{winner.effective_weight}")
+          winner
+        end
+
+        def lane_type_for(operation)
+          Legion::Extensions::Llm::Taxonomies.lane_type_for(operation: operation)
         end
       end
     end

data/lib/legion/llm/router/settings_snapshot.rb

@@ -15,12 +15,11 @@ module Legion
 
         TIER_KEYS             = %i[direct local fleet cloud frontier].freeze
         ALLOWED_ALIAS_META    = %i[owned_by created context_window max_output_tokens].freeze
-        IDENTITY_WEIGHT       = 1
         # Shared 3-level settings cascade (lex-llm): provider -> instance ->
         # model, most-specific-first. The instance leg is the operator's
         # CONFIG NAME (InstanceKey#instance_id), never a derived id.
         CASCADE               = Legion::Extensions::Llm::SettingsCascade
-        private_constant :TIER_KEYS, :ALLOWED_ALIAS_META, :IDENTITY_WEIGHT, :CASCADE
+        private_constant :TIER_KEYS, :ALLOWED_ALIAS_META, :CASCADE
 
         # ------------------------------------------------------------------ #
         # Public factory                                                       #
@@ -51,29 +50,6 @@ module Legion
                     :auto_routing_model_aliases,
                     :auto_routing_model_alias_metadata
 
-        # ------------------------------------------------------------------ #
-        # Per-lane weight inputs (called per candidate during ranking)        #
-        # ------------------------------------------------------------------ #
-
-        # Returns a frozen Hash { tier:, provider:, instance:, model_or_offering: }
-        # where each value is a positive Integer >= 1 (missing component → identity 1).
-        # The provider/instance/model scopes are read through the lex-llm
-        # cascade, keyed by the config name (lane.instance_id): the instance
-        # leg is instances.<name>, the model leg is the instance's models.<model>
-        # entry overriding the provider's models.<model> entry. A zero tier
-        # weight is stored as-is (disabled lane); callers check for zero.
-        def weight_inputs_for(lane:)
-          tier_w  = tier_weights[lane.tier] || IDENTITY_WEIGHT
-          prov    = ext_llm_provider(lane.provider_family)
-          inst    = ext_llm_instance(prov, lane.instance_id)
-          prov_w  = CASCADE.lookup(prov, :weight) || IDENTITY_WEIGHT
-          inst_w  = CASCADE.lookup(inst, :weight) || IDENTITY_WEIGHT
-          off_entry = CASCADE.lookup(CASCADE.lookup(prov, :offerings), lane.offering_id)
-          model_cfg = CASCADE.merge_model_scopes(provider_conf: prov, instance_cfg: inst, model: lane.model)
-          model_w = CASCADE.lookup(off_entry, :weight) || CASCADE.lookup(model_cfg, :weight) || IDENTITY_WEIGHT
-          { tier: tier_w, provider: prov_w, instance: inst_w, model_or_offering: model_w }.freeze
-        end
-
         # Returns { min: Integer_or_nil, max: Integer_or_nil } or nil when no
         # preferred range is configured. Resolved through the lex-llm 3-level
         # cascade (provider -> instance -> model, most-specific-first) keyed

data/lib/legion/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module LLM
-    VERSION = '0.16.3'
+    VERSION = '0.16.8'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-llm
 version: !ruby/object:Gem::Version
-  version: 0.16.3
+  version: 0.16.8
 platform: ruby
 authors:
 - Esity
@@ -141,14 +141,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 0.7.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 0.7.5
 - !ruby/object:Gem::Dependency
   name: pdf-reader
   requirement: !ruby/object:Gem::Requirement