lex-llm 0.6.16 → 0.7.2

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

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/inventory/errors'
+require 'legion/extensions/llm/inventory/immutable_value'
+require 'legion/extensions/llm/inventory/identity'
+require 'legion/extensions/llm/inventory/callable_handle'
+require 'legion/extensions/llm/inventory/records'
+require 'legion/extensions/llm/taxonomies'
+
+module Legion
+  module Extensions
+    module Llm
+      module Routing
+        # Documentation namespace anchor for the request-local routing records
+        # defined in this file: AttemptTargetKey, QuotaDomainKey, Exclusion,
+        # Selection, Rejection, and BodyModelHintDecision. The records live
+        # directly under Routing so their canonical constant paths stay flat.
+        module Records; end
+
+        # The canonical request-local exclusion target: provider family, exact
+        # instance ID, and model. No operation, offering/lane ID, generation,
+        # tier, weight, or affinity. See section 15.1.
+        AttemptTargetKey = ::Data.define(:provider_family, :instance_id, :model) do
+          def initialize(provider_family:, instance_id:, model:)
+            key = Legion::Extensions::Llm::Inventory::Identity::InstanceKey.new(
+              provider_family: provider_family, instance_id: instance_id
+            )
+            model_text = Legion::Extensions::Llm::Inventory::Identity.normalize_text(value: model, field: :model)
+            super(provider_family: key.provider_family, instance_id: key.instance_id, model: model_text)
+          end
+        end
+
+        # A non-secret, provider-scoped quota domain. Equality never crosses
+        # provider family. See section 15.2.
+        QuotaDomainKey = ::Data.define(:provider_family, :opaque_id) do
+          def initialize(provider_family:, opaque_id:)
+            super(
+              provider_family: Legion::Extensions::Llm::Inventory::RecordSupport.normalize_provider_family(
+                value: provider_family
+              ),
+              opaque_id: Legion::Extensions::Llm::Inventory::Identity.normalize_text(value: opaque_id, field: :opaque_id)
+            )
+          end
+        end
+
+        # A request-local or attempt-group exclusion of a typed target. See 15.3.
+        Exclusion = ::Data.define(:target_kind, :target, :reason, :evidence, :lifetime) do
+          def initialize(target_kind:, target:, reason:, evidence:, lifetime:)
+            raise Legion::Extensions::Llm::Inventory::Errors::ValidationError, 'invalid target_kind' unless Legion::Extensions::Llm::Taxonomies::EXCLUSION_TARGET_KINDS.include?(target_kind)
+            raise Legion::Extensions::Llm::Inventory::Errors::ValidationError, 'invalid lifetime' unless Legion::Extensions::Llm::Taxonomies::EXCLUSION_LIFETIMES.include?(lifetime)
+
+            super(
+              target_kind: target_kind,
+              target: normalize_target(target_kind, target),
+              reason: Legion::Extensions::Llm::Inventory::RecordSupport.sanitized_reason(value: reason, field: :reason),
+              evidence: Legion::Extensions::Llm::Inventory::ImmutableValue.copy_and_freeze(value: evidence, field: :evidence),
+              lifetime: lifetime
+            )
+          end
+
+          def normalize_target(target_kind, target)
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            case target_kind
+            when :attempt_target
+              raise errors::ValidationError, 'attempt_target target must be an AttemptTargetKey' unless target.is_a?(AttemptTargetKey)
+
+              target
+            when :instance
+              raise errors::ValidationError, 'instance target must be an InstanceKey' unless target.is_a?(Legion::Extensions::Llm::Inventory::Identity::InstanceKey)
+
+              target
+            when :quota_domain
+              raise errors::ValidationError, 'quota_domain target must be a QuotaDomainKey' unless target.is_a?(QuotaDomainKey)
+
+              target
+            when :provider
+              Legion::Extensions::Llm::Inventory::RecordSupport.normalize_provider_family(value: target, field: :target)
+            else # :lane, :offering, :model
+              Legion::Extensions::Llm::Inventory::Identity.normalize_text(value: target, field: target_kind)
+            end
+          end
+        end
+
+        # An immutable selected target produced by legion-llm's selector and
+        # consumed by dispatch. lex-llm validates cross-field identity only; it
+        # does not compute routing or choose a lane. See section 15.4.
+        Selection = ::Data.define(
+          :inventory_generation, :lane_id, :instance_key, :offering_id, :provider_family, :instance_id,
+          :model, :operation, :callable_handle, :publisher_token_id, :capability_evidence, :context_evidence,
+          :weight_inputs, :base_weight, :preference_ppm, :effective_weight, :rendezvous_score
+        ) do
+          def initialize(**kwargs)
+            Legion::Extensions::Llm::Inventory::RecordSupport.check_unknown_kwargs!(kwargs: kwargs, members: self.class.members)
+            super(**identity_attributes(kwargs).merge(scoring_attributes(kwargs)))
+          end
+
+          def identity_attributes(kwargs)
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            identity = Legion::Extensions::Llm::Inventory::Identity
+            instance_key = kwargs[:instance_key]
+            callable_handle = kwargs[:callable_handle]
+            raise errors::ValidationError, 'instance_key must be an InstanceKey' unless instance_key.is_a?(identity::InstanceKey)
+            raise errors::ValidationError, 'callable_handle must be a CallableHandle' unless callable_handle.is_a?(Legion::Extensions::Llm::Inventory::CallableHandle)
+
+            canonical_model = identity.normalize_text(value: kwargs[:model], field: :model)
+            canonical_operation = Legion::Extensions::Llm::Taxonomies.normalize_operation(value: kwargs[:operation], allow_aliases: false)
+            family = Legion::Extensions::Llm::Inventory::RecordSupport.normalize_provider_family(value: kwargs[:provider_family])
+            normalized_instance = identity.normalize_text(value: kwargs[:instance_id], field: :instance_id)
+            unless family == instance_key.provider_family && normalized_instance == instance_key.instance_id
+              raise errors::ValidationError, 'provider_family and instance_id must equal instance_key'
+            end
+
+            offering_id = kwargs[:offering_id]
+            validate_offering_id_shape!(offering_id)
+            identity.validate_lane_id!(
+              value: kwargs[:lane_id], instance_key: instance_key, operation: canonical_operation,
+              model: canonical_model, offering_id: offering_id
+            )
+            validate_publisher_token_id!(kwargs[:publisher_token_id])
+
+            {
+              lane_id: kwargs[:lane_id].dup.freeze, instance_key: instance_key, offering_id: offering_id.dup.freeze,
+              provider_family: family, instance_id: normalized_instance, model: canonical_model,
+              operation: canonical_operation, callable_handle: callable_handle,
+              publisher_token_id: kwargs[:publisher_token_id].dup.freeze
+            }
+          end
+
+          def scoring_attributes(kwargs)
+            support = Legion::Extensions::Llm::Inventory::RecordSupport
+            base_weight = kwargs[:base_weight]
+            frozen_weight_inputs = validate_weight_inputs!(kwargs[:weight_inputs], base_weight)
+            validate_weights!(base_weight, kwargs[:preference_ppm], kwargs[:effective_weight], kwargs[:rendezvous_score])
+
+            {
+              inventory_generation: support.nonnegative_integer(value: kwargs[:inventory_generation], field: :inventory_generation),
+              capability_evidence: support.validate_capability_evidence!(kwargs[:capability_evidence]),
+              context_evidence: support.positive_int_value_evidence!(kwargs[:context_evidence], :context_evidence),
+              weight_inputs: frozen_weight_inputs, base_weight: base_weight, preference_ppm: kwargs[:preference_ppm],
+              effective_weight: kwargs[:effective_weight], rendezvous_score: kwargs[:rendezvous_score]
+            }
+          end
+
+          def attempt_target_key
+            AttemptTargetKey.new(provider_family: provider_family, instance_id: instance_id, model: model)
+          end
+
+          def validate_offering_id_shape!(offering_id)
+            return if offering_id.is_a?(::String) && offering_id.match?(/\Aoff:v1:[0-9a-f]{64}\z/)
+
+            raise Legion::Extensions::Llm::Inventory::Errors::ValidationError, 'offering_id must have the off:v1: shape'
+          end
+
+          def validate_publisher_token_id!(publisher_token_id)
+            return if publisher_token_id.is_a?(::String) && publisher_token_id.start_with?('ptok:v1:') &&
+                      publisher_token_id.length > 'ptok:v1:'.length
+
+            raise Legion::Extensions::Llm::Inventory::Errors::ValidationError, 'publisher_token_id must be a ptok:v1: String'
+          end
+
+          def validate_weight_inputs!(weight_inputs, base_weight)
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            unless weight_inputs.is_a?(::Hash) && weight_inputs.keys.sort == %i[instance model_or_offering provider tier]
+              raise errors::ValidationError, 'weight_inputs must have keys tier/provider/instance/model_or_offering'
+            end
+            raise errors::ValidationError, 'weight_inputs values must be positive Integers' unless weight_inputs.values.all? { |value| value.is_a?(::Integer) && value.positive? }
+
+            product = weight_inputs.values.reduce(1, :*)
+            raise errors::ValidationError, 'base_weight must equal the product of weight_inputs' unless base_weight == product
+
+            weight_inputs.dup.freeze
+          end
+
+          def validate_weights!(base_weight, preference_ppm, effective_weight, rendezvous_score)
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            raise errors::ValidationError, 'preference_ppm must be an Integer in 500_000..1_500_000' unless preference_ppm.is_a?(::Integer) && (500_000..1_500_000).cover?(preference_ppm)
+            raise errors::ValidationError, 'effective_weight must equal base_weight * preference_ppm' unless effective_weight == base_weight * preference_ppm
+            return if rendezvous_score.is_a?(::Integer) && (0...(2**256)).cover?(rendezvous_score)
+
+            raise errors::ValidationError, 'rendezvous_score must be an Integer in 0...(2**256)'
+          end
+        end
+
+        # A routing rejection diagnosis. lex-llm validates/holds the value;
+        # legion-llm constructs routing diagnoses and HTTP mappings. See 15.5.
+        Rejection = ::Data.define(
+          :kind, :reason, :inventory_generation, :candidate_counts, :explicit_pins, :http_status, :code
+        ) do
+          def initialize(**kwargs)
+            kwargs = { explicit_pins: {}, http_status: nil, code: nil }.merge(kwargs)
+            Legion::Extensions::Llm::Inventory::RecordSupport.check_unknown_kwargs!(kwargs: kwargs, members: self.class.members)
+            support = Legion::Extensions::Llm::Inventory::RecordSupport
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            raise errors::ValidationError, 'kind must be a Taxonomies::REJECTION_KINDS value' unless Legion::Extensions::Llm::Taxonomies::REJECTION_KINDS.include?(kwargs[:kind])
+
+            super(
+              kind: kwargs[:kind],
+              reason: support.sanitized_reason(value: kwargs[:reason], field: :reason),
+              inventory_generation: support.nonnegative_integer(value: kwargs[:inventory_generation], field: :inventory_generation),
+              candidate_counts: validate_candidate_counts!(kwargs[:candidate_counts]),
+              explicit_pins: validate_explicit_pins!(kwargs[:explicit_pins]),
+              http_status: validate_http_status!(kwargs[:http_status]),
+              code: validate_code!(kwargs[:code])
+            )
+          end
+
+          def validate_candidate_counts!(candidate_counts)
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            raise errors::ValidationError, 'candidate_counts must be a Hash' unless candidate_counts.is_a?(::Hash)
+
+            candidate_counts.each do |key, value|
+              raise errors::ValidationError, 'candidate_counts keys must be Symbols' unless key.is_a?(::Symbol)
+              raise errors::ValidationError, 'candidate_counts values must be nonnegative Integers' unless value.is_a?(::Integer) && !value.negative?
+            end
+            candidate_counts.dup.freeze
+          end
+
+          def validate_explicit_pins!(explicit_pins)
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            raise errors::ValidationError, 'explicit_pins must be a Hash' unless explicit_pins.is_a?(::Hash)
+            unless explicit_pins.keys.all? { |key| %i[provider instance model tier].include?(key) }
+              raise errors::ValidationError, 'explicit_pins may contain only provider/instance/model/tier'
+            end
+
+            Legion::Extensions::Llm::Inventory::ImmutableValue.copy_and_freeze(value: explicit_pins, field: :explicit_pins)
+          end
+
+          def validate_http_status!(http_status)
+            return nil if http_status.nil?
+            return http_status if http_status.is_a?(::Integer) && (100..599).cover?(http_status)
+
+            raise Legion::Extensions::Llm::Inventory::Errors::ValidationError, 'http_status must be nil or 100..599'
+          end
+
+          def validate_code!(code)
+            return nil if code.nil?
+            return code if code.is_a?(::Symbol)
+            return code.dup.freeze if code.is_a?(::String) && !code.strip.empty?
+
+            raise Legion::Extensions::Llm::Inventory::Errors::ValidationError, 'code must be nil or a nonempty Symbol/String'
+          end
+        end
+
+        # The disposition of a body-supplied model hint. The record performs no
+        # matching and cannot dispatch. See section 15.6.
+        BodyModelHintDecision = ::Data.define(
+          :requested_model, :disposition, :model_constraint, :matched_whitelist, :matched_blacklist, :settings_generation
+        ) do
+          def initialize(**kwargs)
+            kwargs = { model_constraint: nil, matched_whitelist: nil, matched_blacklist: nil }.merge(kwargs)
+            Legion::Extensions::Llm::Inventory::RecordSupport.check_unknown_kwargs!(kwargs: kwargs, members: self.class.members)
+            support = Legion::Extensions::Llm::Inventory::RecordSupport
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            disposition = kwargs[:disposition]
+            raise errors::ValidationError, 'invalid disposition' unless Legion::Extensions::Llm::Taxonomies::BODY_MODEL_HINT_DISPOSITIONS.include?(disposition)
+
+            normalized_requested = optional_text(kwargs[:requested_model], :requested_model)
+            normalized_constraint = optional_text(kwargs[:model_constraint], :model_constraint)
+            validate_disposition_rules!(disposition, normalized_requested, normalized_constraint)
+
+            super(
+              requested_model: normalized_requested,
+              disposition: disposition,
+              model_constraint: normalized_constraint,
+              matched_whitelist: optional_text(kwargs[:matched_whitelist], :matched_whitelist),
+              matched_blacklist: optional_text(kwargs[:matched_blacklist], :matched_blacklist),
+              settings_generation: support.nonnegative_integer(value: kwargs[:settings_generation], field: :settings_generation)
+            )
+          end
+
+          def optional_text(value, field)
+            return nil if value.nil?
+
+            Legion::Extensions::Llm::Inventory::Identity.normalize_text(value: value, field: field)
+          end
+
+          def validate_disposition_rules!(disposition, requested_model, model_constraint)
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            raise errors::ValidationError, 'only honored may carry a model_constraint' if disposition != :honored && !model_constraint.nil?
+            return unless disposition == :absent && !requested_model.nil?
+
+            raise errors::ValidationError, 'absent must carry a nil requested_model'
+          end
+        end
+      end
+    end
+  end
+end

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/taxonomies.rb

@@ -1,13 +1,103 @@
 # frozen_string_literal: true
 
+require 'legion/extensions/llm/inventory/errors'
+
 module Legion
   module Extensions
     module Llm
+      # Frozen vocabularies shared across routing, inventory, and provider
+      # contracts: legacy tier/type/circuit enums plus the SSOT v3 operation,
+      # evidence, availability, outcome, and rejection enums.
       module Taxonomies
         TIERS           = %i[direct local fleet cloud frontier].freeze
         TYPES           = %i[inference embedding image audio].freeze
         CIRCUIT_STATES  = %i[closed half_open open].freeze
         HEALTH_KEYS     = %i[circuit_state denied available adjustment].freeze
+
+        # --- SSOT v3 runtime-contract enums (phase-1-lex-llm-additive.md section 6) ---
+        OPERATIONS = %i[
+          chat stream_chat embed image transcribe translate speak moderate count_tokens
+        ].freeze
+
+        CAPABILITY_EVIDENCE_STATES = %i[supported unsupported unknown].freeze
+        OPERATION_EVIDENCE_STATES = %i[supported unsupported unknown].freeze
+        VALUE_EVIDENCE_STATES = %i[known unknown].freeze
+        AVAILABILITY_STATES = %i[initializing available unavailable].freeze
+        AVAILABILITY_SOURCES = %i[startup_readiness readiness dispatch].freeze
+        PROBE_OUTCOMES = %i[success failure].freeze
+        PUBLICATION_STATES = %i[initializing complete].freeze
+        CALLABLE_STATES = %i[active retiring disposed].freeze
+
+        MUTATION_REASONS = %i[
+          claimed activated snapshot_replaced readiness_observed instance_unavailable
+          instance_recovered initial_readiness_failed removed stale_publisher stale_probe
+          already_removed
+        ].freeze
+
+        PROVIDER_OUTCOMES = %i[
+          success instance_unavailable overloaded model_not_ready rate_limited
+          authentication authorization billing policy invalid_request model_missing
+          context_rejected safety_refusal malformed_output tool_failure timeout
+          connection_failure provider_error cancelled client_disconnect
+        ].freeze
+
+        REJECTION_KINDS = %i[
+          invalid_routing_context invalid_request policy_denied failed_dependency
+          too_early service_unavailable context_rejected attempts_exhausted stale_selection
+        ].freeze
+
+        EXCLUSION_TARGET_KINDS = %i[
+          attempt_target lane offering instance provider model quota_domain
+        ].freeze
+
+        EXCLUSION_LIFETIMES = %i[request attempt_group].freeze
+
+        BODY_MODEL_HINT_DISPOSITIONS = %i[
+          absent auto superseded_by_explicit_model ignored_disabled
+          ignored_not_whitelisted ignored_blacklisted honored
+        ].freeze
+
+        EVIDENCE_SOURCES = %i[
+          provider_implementation model_metadata provider_catalog probe provider_envelope
+          model_override instance_override provider_override default_false absent guessed
+          failed_probe inconclusive_probe
+        ].freeze
+
+        UNKNOWN_ONLY_EVIDENCE_SOURCES = %i[
+          model_override instance_override provider_override default_false absent guessed
+          failed_probe inconclusive_probe
+        ].freeze
+
+        # Only these aliases are accepted, and only when allow_aliases: true.
+        OPERATION_ALIASES = {
+          stream: :stream_chat,
+          embedding: :embed,
+          moderation: :moderate,
+          audio_translation: :translate,
+          speech: :speak
+        }.freeze
+
+        module_function
+
+        # Normalize an operation to one of OPERATIONS. Ingress and protocol-v2
+        # compatibility adapters pass allow_aliases: true; registry records and
+        # exact-execution envelopes pass false. Unknown, empty, or invalid UTF-8
+        # input always raises Inventory::Errors::ValidationError.
+        def normalize_operation(value:, allow_aliases: false)
+          raise Inventory::Errors::ValidationError, 'operation must be a String or Symbol' unless value.is_a?(::String) || value.is_a?(::Symbol)
+
+          string = value.to_s
+          raise Inventory::Errors::ValidationError, 'operation is not valid UTF-8' unless [::Encoding::UTF_8, ::Encoding::US_ASCII].include?(string.encoding) && string.valid_encoding?
+
+          trimmed = string.strip
+          raise Inventory::Errors::ValidationError, 'operation must not be empty' if trimmed.empty?
+
+          candidate = trimmed.to_sym
+          return candidate if OPERATIONS.include?(candidate)
+          return OPERATION_ALIASES[candidate] if allow_aliases && OPERATION_ALIASES.key?(candidate)
+
+          raise Inventory::Errors::ValidationError, "operation is not a canonical operation (#{candidate})"
+        end
       end
     end
   end

data/lib/legion/extensions/llm/transport/messages/fleet_error.rb

@@ -54,7 +54,9 @@ module Legion
                 message: @options[:message],
                 error_class: @options[:error_class],
                 retryable: @options[:retryable],
-                metadata: @options[:metadata] || {}
+                metadata: @options[:metadata] || {},
+                execution_contract: @options[:execution_contract],
+                offering_id: @options[:offering_id]
               ).compact
             end
           end

data/lib/legion/extensions/llm/transport/messages/fleet_response.rb

@@ -53,7 +53,9 @@ module Legion
                 tool_calls: @options[:tool_calls],
                 usage: @options[:usage] || {},
                 finish_reason: @options[:finish_reason],
-                metadata: @options[:metadata] || {}
+                metadata: @options[:metadata] || {},
+                execution_contract: @options[:execution_contract],
+                offering_id: @options[:offering_id]
               ).compact
             end
           end

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

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

data/lib/legion/extensions/llm.rb

@@ -45,6 +45,24 @@ 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'
+      require_relative 'llm/inventory/identity'
+      require_relative 'llm/inventory/evidence'
+      require_relative 'llm/inventory/callable_handle'
+      require_relative 'llm/inventory/probe_token'
+      require_relative 'llm/inventory/records'
+      require_relative 'llm/inventory/snapshot'
+      require_relative 'llm/inventory/registry'
+      require_relative 'llm/inventory/publisher'
+      require_relative 'llm/inventory/probe_coordinator'
+      require_relative 'llm/routing/records'
+      require_relative 'llm/routing/provider_outcome'
+
       # --- Base value objects (no internal deps) ---
       require_relative 'llm/mime_type'
       require_relative 'llm/model/info'

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",