lex-llm 0.6.16 → 0.7.2

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

@@ -1,9 +1,23 @@
 # frozen_string_literal: true
 
+require 'legion/logging'
+require 'legion/extensions/llm/inventory/errors'
+require 'legion/extensions/llm/inventory/identity'
+require 'legion/extensions/llm/inventory/snapshot'
+require 'legion/extensions/llm/taxonomies'
+
 module Legion
   module Extensions
     module Llm
       module Inventory
+        # DEPRECATED (Phase 4 removal): the only Phase 1 file permitted to hold a
+        # direct `Legion::LLM::Inventory` reverse reference. Old released provider
+        # actors keep using ScopedRefresher#tick until their Phase 2 migration; a
+        # migrated actor instead injects ScopedRefresher::LegacyCoordinatorAdapter
+        # into Inventory::Publisher and never calls #tick. Neither old lane hashes
+        # nor old health feed the new registry. Phase 4 deletes this file once
+        # every provider and coordinator floor has migrated.
+        #
         # Mix into a Legion::Extensions::Llm::*::Actors::DiscoveryRefresh class.
         # The host class must include Legion::Extensions::Helpers::Lex (auto-injects
         # log / settings / handle_exception / cache_*) and define:
@@ -98,6 +112,198 @@ module Legion
 
             error.message&.match?(/unauthorized|invalid[_ ]api[_ ]key|invalid[_ ]credentials|forbidden/i)
           end
+
+          # One-way, post-commit projection of an already-committed new Snapshot
+          # into the old Legion::LLM::Inventory coordinator, for the mixed-version
+          # window only. It never rediscovers, selects, authorizes new state, or
+          # feeds an old fact back into the new Registry. See section 13.3.
+          class LegacyCoordinatorAdapter
+            include Legion::Logging::Helper
+
+            HEALTHY_COMPAT = { circuit_state: :closed, denied: false, available: true, adjustment: 0 }.freeze
+            LEGACY_TYPES = { embed: :embedding, image: :image, transcribe: :audio, translate: :audio, speak: :audio }.freeze
+            LEGACY_CAPABILITIES = {
+              chat: :completion, stream_chat: :streaming, embed: :embedding, image: :image,
+              transcribe: :audio_transcription, translate: :audio_transcription, speak: :audio_speech, moderate: :moderation
+            }.freeze
+
+            def initialize(provider_family:, legacy_instance_ids_by_instance: {})
+              @provider_family = canonical_family(provider_family)
+              @legacy_instance_ids = deep_freeze_legacy_ids(legacy_instance_ids_by_instance)
+              @published_ids_by_instance = {}.freeze
+              @mutex = Mutex.new
+            end
+
+            def sync_snapshot(snapshot:, instance_key:, mutation_reason:)
+              validate_inputs!(snapshot, instance_key, mutation_reason)
+              return :not_loaded unless legacy_inventory_available?
+
+              project(snapshot, instance_key)
+            end
+
+            private
+
+            def project(snapshot, instance_key)
+              @mutex.synchronize { project_locked(snapshot, instance_key) }
+              :applied
+            rescue StandardError => e
+              handle_exception(
+                e, handled: true, level: :warn, operation: 'inventory.scoped_refresher.legacy_projection',
+                   provider_family: @provider_family, instance_id: instance_key.instance_id,
+                   source_generation: snapshot.generation
+              )
+              :failed
+            end
+
+            def project_locked(snapshot, instance_key)
+              desired = desired_lanes(snapshot, instance_key)
+              written = write_desired(desired)
+              reconcile_deletions(instance_key, written)
+              @published_ids_by_instance = @published_ids_by_instance.merge(
+                instance_key.instance_id => written.to_a.freeze
+              ).freeze
+            end
+
+            def desired_lanes(snapshot, instance_key)
+              record = snapshot.instance(instance_key: instance_key)
+              return {} if record.nil? || record.availability.state != :available
+
+              build_desired(group_lanes(snapshot, instance_key), snapshot.generation)
+            end
+
+            def group_lanes(snapshot, instance_key)
+              groups = {}
+              snapshot.lanes_for(instance_key: instance_key).each do |lane|
+                type = LEGACY_TYPES.fetch(lane.operation, :inference)
+                key = [lane.tier, instance_key.provider_family, instance_key.instance_id, type, lane.model]
+                group = (groups[key] ||= new_group(instance_key, lane, type))
+                accumulate_group(group, lane)
+              end
+              groups
+            end
+
+            def new_group(instance_key, lane, type)
+              {
+                tier: lane.tier, provider_family: instance_key.provider_family, instance_id: instance_key.instance_id,
+                type: type, model: lane.model, offering_ids: Set.new, capabilities: Set.new,
+                context_values: Set.new, max_output_values: Set.new
+              }
+            end
+
+            def accumulate_group(group, lane)
+              group[:offering_ids] << lane.offering_id
+              mapped = LEGACY_CAPABILITIES[lane.operation]
+              group[:capabilities] << mapped if mapped
+              lane.capability_evidence.each { |capability, evidence| group[:capabilities] << capability if evidence.supported? }
+              group[:context_values] << lane.context_evidence.value if lane.context_evidence.known?
+              group[:max_output_values] << lane.max_output_evidence.value if lane.max_output_evidence.known?
+            end
+
+            def build_desired(groups, generation)
+              by_id = {}
+              groups.each_value do |group|
+                legacy_id = ScopedRefresher.compose_id(identity_fields(group))
+                (by_id[legacy_id] ||= []) << group
+              end
+
+              by_id.each_with_object({}) do |(legacy_id, colliding), desired|
+                if colliding.size > 1 || colliding.first[:offering_ids].size != 1
+                  log.warn("[llm][inventory][legacy_adapter] action=fail_closed reason=ambiguous_group legacy_id=#{legacy_id}")
+                  next
+                end
+                desired[legacy_id] = build_lane_hash(legacy_id, colliding.first, generation)
+              end
+            end
+
+            def identity_fields(group)
+              {
+                tier: group[:tier], provider_family: group[:provider_family],
+                instance_id: group[:instance_id], type: group[:type], model: group[:model]
+              }.freeze
+            end
+
+            def build_lane_hash(legacy_id, group, generation)
+              {
+                id: legacy_id, tier: group[:tier], provider_family: group[:provider_family],
+                provider_instance: group[:instance_id], instance_id: group[:instance_id], type: group[:type],
+                model: group[:model], offering_id: group[:offering_ids].first,
+                capabilities: group[:capabilities].to_a.sort, limits: build_limits(group),
+                metadata: { ssot_v3_compatibility_projection: true, source_generation: generation }, enabled: true
+              }
+            end
+
+            def build_limits(group)
+              limits = {}
+              limits[:context_window] = group[:context_values].first if group[:context_values].size == 1
+              limits[:max_output_tokens] = group[:max_output_values].first if group[:max_output_values].size == 1
+              limits
+            end
+
+            def write_desired(desired)
+              written = Set.new
+              desired.each do |legacy_id, lane_hash|
+                result = ::Legion::LLM::Inventory.write_lane(lane: lane_hash, health: HEALTHY_COMPAT)
+                written << legacy_id unless result.nil?
+              end
+              written
+            end
+
+            def reconcile_deletions(instance_key, written)
+              tracked = @published_ids_by_instance.fetch(instance_key.instance_id, [])
+              candidates = (tracked.to_a + read_current_old_ids(instance_key).to_a).uniq
+              candidates.each do |old_id|
+                next if written.include?(old_id)
+
+                ::Legion::LLM::Inventory.delete_lane(id: old_id)
+              end
+            end
+
+            def read_current_old_ids(instance_key)
+              instance_ids_to_read(instance_key).each_with_object(Set.new) do |instance_id, ids|
+                lanes = ::Legion::LLM::Inventory.lanes_for(provider: @provider_family, instance: instance_id)
+                Array(lanes).each { |lane| ids << (lane.is_a?(::Hash) ? lane[:id] : lane) }
+              end
+            end
+
+            def instance_ids_to_read(instance_key)
+              ([instance_key.instance_id] + @legacy_instance_ids.fetch(instance_key.instance_id, [])).uniq
+            end
+
+            def validate_inputs!(snapshot, instance_key, mutation_reason)
+              raise Errors::ValidationError, 'snapshot must be an Inventory::Snapshot' unless snapshot.is_a?(Snapshot)
+              unless instance_key.is_a?(Identity::InstanceKey) && instance_key.provider_family == @provider_family
+                raise Errors::ValidationError, 'instance_key must belong to the adapter provider family'
+              end
+              return if Taxonomies::MUTATION_REASONS.include?(mutation_reason)
+
+              raise Errors::ValidationError, 'mutation_reason must be a Taxonomies::MUTATION_REASONS value'
+            end
+
+            def legacy_inventory_available?
+              defined?(::Legion::LLM::Inventory) &&
+                ::Legion::LLM::Inventory.respond_to?(:lanes_for) &&
+                ::Legion::LLM::Inventory.respond_to?(:write_lane) &&
+                ::Legion::LLM::Inventory.respond_to?(:delete_lane)
+            end
+
+            def canonical_family(value)
+              text = Identity.normalize_text(value: value, field: :provider_family).downcase
+              raise Errors::ValidationError, 'provider_family must be snake-case ASCII' unless text.match?(/\A[a-z][a-z0-9_]*\z/)
+
+              text.to_sym
+            end
+
+            def deep_freeze_legacy_ids(mapping)
+              raise Errors::ValidationError, 'legacy_instance_ids_by_instance must be a Hash' unless mapping.is_a?(::Hash)
+
+              mapping.each_with_object({}) do |(key, values), frozen|
+                raise Errors::ValidationError, 'legacy instance id keys must be Strings' unless key.is_a?(::String)
+                raise Errors::ValidationError, 'legacy superseded ids must be a nonempty Array of Strings' unless values.is_a?(::Array) && !values.empty? && values.all?(::String)
+
+                frozen[key.dup.freeze] = values.map { |value| value.dup.freeze }.freeze
+              end.freeze
+            end
+          end
         end
       end
     end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/inventory/errors'
+require 'legion/extensions/llm/inventory/identity'
+require 'legion/extensions/llm/inventory/records'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # A structurally immutable, generation-tagged read model of the registry.
+        # Lookups return the frozen record or nil and never synthesize a default.
+        # `instances_by_key` contains only activated instances;
+        # `publication_status_by_key` also contains initializing claims. A caller
+        # cannot observe a later inventory-record or generation mutation through
+        # an older snapshot; the captured CallableHandle lifecycle is the single
+        # intentional exception. See phase-1-lex-llm-additive.md section 11.3.
+        class Snapshot
+          attr_reader :generation
+
+          def initialize(generation:, instances_by_key:, offerings_by_id:, lanes_by_id:, publication_status_by_key:)
+            @generation = generation
+            @instances_by_key = order_instances(instances_by_key).freeze
+            @offerings_by_id = offerings_by_id.dup.freeze
+            @lanes_by_id = lanes_by_id.dup.freeze
+            @publication_status_by_key = order_instances(publication_status_by_key).freeze
+            @ordered_offerings = @offerings_by_id.keys.sort.map { |id| @offerings_by_id[id] }.freeze
+            @ordered_lanes = @lanes_by_id.keys.sort.map { |id| @lanes_by_id[id] }.freeze
+            freeze
+          end
+
+          def instance(instance_key:)
+            @instances_by_key[instance_key]
+          end
+
+          def offering(offering_id:)
+            @offerings_by_id[offering_id]
+          end
+
+          def lane(lane_id:)
+            @lanes_by_id[lane_id]
+          end
+
+          def lanes_for(instance_key:)
+            @ordered_lanes.select { |lane| lane.instance_key == instance_key }.freeze
+          end
+
+          def offerings_for(instance_key:)
+            @ordered_offerings.select { |offering| offering.instance_key == instance_key }.freeze
+          end
+
+          def publication_status(instance_key:)
+            @publication_status_by_key[instance_key]
+          end
+
+          def each_lane(&block)
+            return to_enum(:each_lane) unless block
+
+            @ordered_lanes.each(&block)
+          end
+
+          def each_offering(&block)
+            return to_enum(:each_offering) unless block
+
+            @ordered_offerings.each(&block)
+          end
+
+          def each_instance(&block)
+            return to_enum(:each_instance) unless block
+
+            @instances_by_key.each_value(&block)
+          end
+
+          def each_publication_status(&block)
+            return to_enum(:each_publication_status) unless block
+
+            @publication_status_by_key.each_value(&block)
+          end
+
+          private
+
+          # Orders InstanceKey entries by [provider_family bytes, instance_id bytes].
+          def order_instances(by_key)
+            by_key.keys.sort_by { |key| [key.provider_family.to_s.b, key.instance_id.b] }
+                  .to_h { |key| [key, by_key[key]] }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -307,6 +307,49 @@ module Legion
           parse_transcription_response(response, model:)
         end
 
+        # Fail-loud base audio operations. Unsupported providers inherit these and
+        # publish OperationEvidence(status: :unsupported) or :unknown; a provider
+        # may publish :supported only when its Phase 2 conformance spec exercises
+        # the actual callable path. Neither method reads configuration or infers a
+        # model. See phase-1-lex-llm-additive.md section 14.1.
+        def translate(audio_file, model:, language:, **provider_options)
+          _ = [audio_file, model, language, provider_options]
+          raise NotImplementedError, "#{self.class} does not implement translate"
+        end
+
+        def speak(text, model:, voice: nil, **provider_options)
+          _ = [text, model, voice, provider_options]
+          raise NotImplementedError, "#{self.class} does not implement speak"
+        end
+
+        # Runtime error-to-outcome normalization consumed by the common
+        # classifier. The inherited base is deliberately conservative: raw 503,
+        # Anthropic-style 529, ServiceUnavailableError, ServerError, and every
+        # unrecognized error return :provider_error, never :instance_unavailable.
+        # Provider PRs override only when their wire semantics supply stronger
+        # evidence. The fallback reason is the bounded exception class name — never
+        # a response body, credential, endpoint, or exception object. It is a base
+        # method, not a REQUIRED_SIGNATURES reflection entry. See Phase 2 §4.5.2.
+        def normalize_dispatch_error(error:)
+          kind = case error
+                 when OverloadedError then :overloaded
+                 when RateLimitError then :rate_limited
+                 when UnauthorizedError then :authentication
+                 when PaymentRequiredError then :billing
+                 when ForbiddenError then :authorization
+                 when ContextLengthExceededError then :context_rejected
+                 when BadRequestError then :invalid_request
+                 when ModelNotFoundError then :model_missing
+                 when ModelNotAllowedError then :policy
+                 when Faraday::TimeoutError, Timeout::Error then :timeout
+                 when Faraday::ConnectionFailed, Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError then :connection_failure
+                 else :provider_error
+                 end
+          reason = error.class.name
+          reason = 'UnknownError' if reason.nil? || reason.empty?
+          Legion::Extensions::Llm::Routing::ProviderOutcome.new(kind: kind, reason: reason)
+        end
+
         def configured?
           configuration_requirements.all? { |req| @config.send(req) }
         end
@@ -537,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
 
@@ -760,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")
           {}
@@ -821,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/routing/lane_key.rb

@@ -4,6 +4,10 @@ module Legion
   module Extensions
     module Llm
       module Routing
+        # DEPRECATED (Phase 4 removal): retained only for protocol-v2 fleet
+        # compatibility. The new canonical execution identity comes solely from
+        # Inventory::Identity (off:v1:/lane:v1:); do not reinterpret an old
+        # five-part lane as a new lane:v1: identity.
         # Builds stable fleet lane keys from provider-neutral model offerings.
         module LaneKey
           module_function

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

@@ -4,6 +4,9 @@ module Legion
   module Extensions
     module Llm
       module Routing
+        # DEPRECATED (Phase 4 removal): kept unchanged for released consumers.
+        # New providers publish Inventory::OfferingDraft; the new registry accepts
+        # no default generated offering_id from this class.
         # Describes one concrete model made available by one provider instance.
         class ModelOffering
           CAPABILITY_ALIASES = {

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

@@ -4,6 +4,8 @@ module Legion
   module Extensions
     module Llm
       module Routing
+        # DEPRECATED (Phase 4 removal): the old mutable registry, kept only for
+        # old callers. It is never returned by Inventory::Registry.snapshot.
         # In-memory index of provider-neutral model offerings.
         class OfferingRegistry
           include Enumerable

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/inventory/errors'
+require 'legion/extensions/llm/inventory/immutable_value'
+require 'legion/extensions/llm/inventory/records'
+require 'legion/extensions/llm/routing/records'
+require 'legion/extensions/llm/taxonomies'
+
+module Legion
+  module Extensions
+    module Llm
+      module Routing
+        # A provider-neutral normalized outcome. Adapters translate wire errors
+        # into one of these kinds; the common classifier branches only on kind,
+        # never on provider identity. The value contains no provider object,
+        # callable, response body, routing weight, or health-mutation
+        # instruction. HTTP 503/529 alone is not an input and cannot manufacture
+        # instance_unavailable. See phase-1-lex-llm-additive.md section 14.2.
+        ProviderOutcome = ::Data.define(:kind, :reason, :quota_domain, :retry_after, :metadata) do
+          def initialize(kind:, reason:, quota_domain: nil, retry_after: nil, metadata: {})
+            support = Legion::Extensions::Llm::Inventory::RecordSupport
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            raise errors::ValidationError, 'kind must be a Taxonomies::PROVIDER_OUTCOMES value' unless Legion::Extensions::Llm::Taxonomies::PROVIDER_OUTCOMES.include?(kind)
+
+            super(
+              kind: kind,
+              reason: support.sanitized_reason(value: reason, field: :reason),
+              quota_domain: validate_quota_domain!(kind, quota_domain),
+              retry_after: validate_retry_after!(retry_after),
+              metadata: support.frozen_metadata(value: metadata)
+            )
+          end
+
+          def validate_quota_domain!(kind, quota_domain)
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            return nil if quota_domain.nil?
+            raise errors::ValidationError, 'quota_domain must be a Routing::QuotaDomainKey' unless quota_domain.is_a?(QuotaDomainKey)
+            raise errors::ValidationError, 'quota_domain is allowed only for rate_limited' unless kind == :rate_limited
+
+            quota_domain
+          end
+
+          def validate_retry_after!(retry_after)
+            return nil if retry_after.nil?
+            return retry_after if retry_after.is_a?(::Numeric) && retry_after.finite? && !retry_after.negative?
+
+            raise Legion::Extensions::Llm::Inventory::Errors::ValidationError,
+                  'retry_after must be nil or a finite nonnegative Numeric'
+          end
+        end
+      end
+    end
+  end
+end