lex-llm 0.7.3 → 0.8.0

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

@@ -11,20 +11,20 @@ module Legion
         # 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.
+        # `publication_status_by_key` also contains initializing claims. Lanes
+        # are keyed by the 5-tuple lane id and iterate in lexicographic id
+        # order (readable iteration). 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:)
+          def initialize(generation:, instances_by_key:, 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
@@ -33,10 +33,6 @@ module Legion
             @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
@@ -45,10 +41,6 @@ module Legion
             @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
@@ -59,12 +51,6 @@ module Legion
             @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
 

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

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+# Direct dependency; the explicit receiver keeps Ruby 4's redundant-require cop from deleting it.
+Kernel.require 'set'
+require 'legion/extensions/llm/inventory/weight_schema'
+require 'legion/extensions/llm/settings_cascade'
+require 'legion/extensions/llm/inventory/identity'
+require 'legion/extensions/llm/taxonomies'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # Tracks configured weight keys that currently have no published lane.
+        class DormantWeightTracker
+          def initialize
+            @dormant = Set.new
+          end
+
+          def observe(configured_keys:, published_keys:)
+            current = Set.new(configured_keys).difference(published_keys)
+            newly_dormant = current.difference(@dormant).sort_by(&:inspect)
+            @dormant.replace(current)
+            newly_dormant
+          end
+
+          def clear!
+            @dormant.clear
+          end
+        end
+
+        # Shared atomic write-time weight publication for existing writer cadences.
+        module WeightReconciler
+          module_function
+
+          def rebuild_offerings(settings:, instance_key:, offerings:)
+            offerings.map do |draft|
+              inputs = WeightSchema.weight_inputs(
+                settings: settings,
+                instance_key: instance_key,
+                model: draft.model,
+                tier: draft.tier,
+                operation_evidence: draft.operation_evidence
+              )
+              draft.with(weight_inputs: inputs, base_weight: WeightSchema.base_weight(inputs))
+            end.freeze
+          end
+
+          # Periodic discovery calls this AFTER its existing network/discovery work. Read
+          # current Settings and perform weight rebuilding, comparison, sequence
+          # allocation, publish, and cache update under the same writer mutex. No Settings
+          # callback or separate reweight path exists.
+          def commit_if_changed!(settings:, instance_id:, state:, discovered_offerings:, **publication)
+            unknown = publication.keys - %i[mutex equivalent replace stable_signature]
+            raise ArgumentError, "unknown publication keyword(s): #{unknown.join(', ')}" unless unknown.empty?
+
+            mutex = publication.fetch(:mutex)
+            equivalent = publication.fetch(:equivalent)
+            replace = publication.fetch(:replace)
+            stable_signature = publication[:stable_signature]
+            mutex.synchronize do
+              offerings = rebuild_offerings(
+                settings: settings, instance_key: state.fetch(:instance_key),
+                offerings: discovered_offerings
+              )
+              return false if equivalent.call(state.fetch(:offerings), offerings)
+
+              if state.fetch(:published)
+                commit_locked!(
+                  instance_id: instance_id, state: state, offerings: offerings,
+                  replace: replace, stable_signature: stable_signature
+                )
+              else
+                cache_locked!(
+                  state: state, offerings: offerings, stable_signature: stable_signature
+                )
+              end
+              true
+            end
+          end
+
+          # Track a claimed but not-yet-activated instance before its readiness I/O. An
+          # ordinary writer pass may refresh its cached weights, but must never send a
+          # replacement for a publication that is still :initializing.
+          def track_initializing!(states:, state_key:, state:, mutex:)
+            mutex.synchronize do
+              state[:published] = false
+              states[state_key] = state
+            end
+            state
+          end
+
+          # Initial and recovery activation both use this helper after readiness succeeds.
+          # Rebuild from current settings and publish under the writer's publication
+          # mutex, then mark the state published only after the publisher call succeeds.
+          def activate_tracked!(settings:, instance_id:, state_key:, state:, **activation)
+            unknown = activation.keys - %i[states mutex probe_token activate activation_sequence stable_signature]
+            raise ArgumentError, "unknown activation keyword(s): #{unknown.join(', ')}" unless unknown.empty?
+
+            states = activation.fetch(:states)
+            mutex = activation.fetch(:mutex)
+            probe_token = activation.fetch(:probe_token)
+            activate = activation.fetch(:activate)
+            activation_sequence = activation.fetch(:activation_sequence)
+            stable_signature = activation[:stable_signature]
+            mutex.synchronize do
+              return false unless states[state_key].equal?(state)
+
+              offerings = rebuild_offerings(
+                settings: settings, instance_key: state.fetch(:instance_key),
+                offerings: state.fetch(:offerings)
+              )
+              sequence = activation_sequence.call(state)
+              activate.call(
+                instance_id: instance_id, state: state, offerings: offerings,
+                sequence: sequence, probe_token: probe_token
+              )
+              state[:sequence] = sequence
+              cache_locked!(
+                state: state, offerings: offerings, stable_signature: stable_signature
+              )
+              state[:published] = true
+              true
+            end
+          end
+
+          # Ordinary ticks call this after reconcile. Dormant observation has the same
+          # cadence as the existing writer; there is no reload callback path.
+          def observe_dormant!(settings:, provider_family:, states:, mutex:, **observation)
+            unknown = observation.keys - %i[tracker dormant_logger]
+            raise ArgumentError, "unknown observation keyword(s): #{unknown.join(', ')}" unless unknown.empty?
+
+            tracker = observation.fetch(:tracker)
+            dormant_logger = observation.fetch(:dormant_logger)
+            mutex.synchronize do
+              observe_dormant_locked!(
+                settings: settings, provider_family: provider_family, states: states,
+                tracker: tracker, dormant_logger: dormant_logger
+              )
+            end
+          end
+
+          def commit_locked!(instance_id:, state:, offerings:, replace:, stable_signature:)
+            sequence = state.fetch(:sequence) + 1
+            replace.call(instance_id: instance_id, state: state, offerings: offerings, sequence: sequence)
+            state[:sequence] = sequence
+            cache_locked!(
+              state: state, offerings: offerings, stable_signature: stable_signature
+            )
+          end
+          private_class_method :commit_locked!
+
+          def cache_locked!(state:, offerings:, stable_signature:)
+            state[:offerings] = offerings
+            state[:signature] = stable_signature.call(offerings) if stable_signature
+          end
+          private_class_method :cache_locked!
+
+          def observe_dormant_locked!(settings:, provider_family:, states:, tracker:,
+                                      dormant_logger:)
+            configured = configured_weight_keys(settings: settings, provider_family: provider_family)
+            published = published_weight_keys(provider_family: provider_family, states: states)
+            tracker.observe(configured_keys: configured, published_keys: published).each do |key|
+              dormant_logger.call(key)
+            end
+          end
+          private_class_method :observe_dormant_locked!
+
+          def configured_weight_keys(settings:, provider_family:)
+            llm = config_hash(settings.dig(:extensions, :llm))
+            provider = config_hash(SettingsCascade.lookup(llm, provider_family))
+            keys = Set.new
+            keys << canonical_key(provider_family, :provider) if weight_present?(provider)
+
+            config_hash(SettingsCascade.lookup(provider, :models)).each do |model, config|
+              keys << canonical_key(provider_family, :model, model.to_s) if weight_present?(config_hash(config))
+            end
+            config_hash(SettingsCascade.lookup(provider, :instances)).each do |instance, config|
+              instance_config = config_hash(config)
+              keys << canonical_key(provider_family, :instance, instance.to_s) if weight_present?(instance_config)
+              config_hash(SettingsCascade.lookup(instance_config, :models)).each do |model, model_config|
+                next unless weight_present?(config_hash(model_config))
+
+                keys << canonical_key(
+                  provider_family, :instance, instance.to_s, :model, model.to_s
+                )
+              end
+            end
+            config_hash(SettingsCascade.lookup(provider, :offerings)).each do |offering_id, config|
+              keys << canonical_key(provider_family, :offering, offering_id.to_s) \
+                if weight_present?(config_hash(config))
+            end
+            keys
+          end
+
+          def published_weight_keys(provider_family:, states:)
+            keys = Set.new
+            states.each_value do |state|
+              next unless state.fetch(:published)
+
+              offerings = Array(state[:offerings])
+              next if offerings.empty?
+
+              instance_key = state.fetch(:instance_key)
+              keys << canonical_key(provider_family, :provider)
+              keys << canonical_key(provider_family, :instance, instance_key.instance_id.to_s)
+              offerings.each do |draft|
+                keys << canonical_key(provider_family, :model, draft.model.to_s)
+                keys << canonical_key(
+                  provider_family, :instance, instance_key.instance_id.to_s,
+                  :model, draft.model.to_s
+                )
+                draft.operation_evidence.each_value do |evidence|
+                  next unless evidence.supported?
+
+                  lane_id = Identity.compose_lane_id(
+                    tier: draft.tier, provider_family: instance_key.provider_family,
+                    instance_id: instance_key.instance_id,
+                    type: Taxonomies.lane_type_for(operation: evidence.operation), model: draft.model
+                  )
+                  keys << canonical_key(provider_family, :offering, lane_id)
+                end
+              end
+            end
+            keys
+          end
+
+          def canonical_key(provider_family, *parts)
+            [provider_family.to_sym, *parts].freeze
+          end
+          private_class_method :canonical_key
+
+          def config_hash(value)
+            return {} if value.nil?
+            return value if value.is_a?(::Hash)
+
+            raise ArgumentError, "weight configuration scope must be a Hash, got #{value.inspect}"
+          end
+          private_class_method :config_hash
+
+          def weight_present?(scope)
+            !SettingsCascade.lookup(scope, :weight).nil?
+          end
+          private_class_method :weight_present?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/settings_cascade'
+require 'legion/extensions/llm/inventory/identity'
+require 'legion/extensions/llm/taxonomies'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # Write-time lane-weight computation (RANKING v2 law): the stateless router
+        # reads the stored scalar; it is computed ONLY here, at write events, from a
+        # live settings read. Each multiplicative axis reads ITS OWN scope — never a
+        # fall-through cascade (a fall-through would double-count the other axes).
+        # The offering-scope settings key is the lane's 5 tuple — operator-readable,
+        # composed via Identity.compose_lane_id.
+        module WeightSchema
+          module_function
+
+          IDENTITY = 100
+
+          # Exact 4-key hash. The offering-scope settings key is the 5 tuple of
+          # the lanes the draft's operation evidence supports (one per distinct
+          # lane type) — finally operator-usable, no digest.
+          def weight_inputs(settings:, instance_key:, model:, tier:, operation_evidence:)
+            llm_conf = scope_hash(settings.dig(:extensions, :llm), path: 'extensions.llm')
+            provider_conf = scope_hash(
+              SettingsCascade.lookup(llm_conf, instance_key.provider_family),
+              path: "extensions.llm.#{instance_key.provider_family}"
+            )
+            instances = scope_hash(
+              SettingsCascade.lookup(provider_conf, :instances), path: 'provider.instances'
+            )
+            instance_cfg = scope_hash(
+              SettingsCascade.lookup(instances, instance_key.instance_id),
+              path: "provider.instances.#{instance_key.instance_id}"
+            )
+            tier_weights = scope_hash(
+              settings.dig(:llm, :routing, :tier_weights), path: 'llm.routing.tier_weights'
+            )
+            offerings = scope_hash(SettingsCascade.lookup(provider_conf, :offerings), path: 'provider.offerings')
+            offering_w = offering_scope_weight(
+              offerings: offerings, instance_key: instance_key, model: model, tier: tier,
+              operation_evidence: operation_evidence
+            )
+            provider_models = scope_hash(
+              SettingsCascade.lookup(provider_conf, :models), path: 'provider.models'
+            )
+            instance_models = scope_hash(
+              SettingsCascade.lookup(instance_cfg, :models), path: 'instance.models'
+            )
+            scope_hash(
+              SettingsCascade.lookup(provider_models, model), path: "provider.models.#{model}"
+            )
+            scope_hash(
+              SettingsCascade.lookup(instance_models, model), path: "instance.models.#{model}"
+            )
+            model_scopes = scope_hash(
+              SettingsCascade.merge_model_scopes(
+                provider_conf: provider_conf, instance_cfg: instance_cfg, model: model
+              ),
+              path: "merged model scope #{model}"
+            )
+
+            model_w = SettingsCascade.lookup(model_scopes, :weight)
+            {
+              tier: component(SettingsCascade.lookup(tier_weights, tier), IDENTITY),
+              provider: component(SettingsCascade.lookup(provider_conf, :weight), IDENTITY),
+              instance: component(SettingsCascade.lookup(instance_cfg, :weight), IDENTITY),
+              # Explicit nil? precedence (NEVER `||`): offering overrides the model
+              # component only; nil offering → model; both nil → identity. A
+              # non-nil non-Integer (false, strings, negatives) RAISES in `component`.
+              model_or_offering: component(offering_w.nil? ? model_w : offering_w, IDENTITY)
+            }
+          end
+
+          # The configured offering-scope weight for the draft: the operator keys
+          # `extensions.llm.<provider>.offerings` by the lane's 5 tuple. The lanes
+          # a draft supports are one 5 tuple per distinct lane type; the draft
+          # carries a SINGLE weight pair, so configured weights across its lanes
+          # must agree — a disagreement is an ambiguous operator input and RAISES
+          # instead of silently picking one.
+          def offering_scope_weight(offerings:, instance_key:, model:, tier:, operation_evidence:)
+            lane_ids = supported_lane_ids(
+              instance_key: instance_key, model: model, tier: tier, operation_evidence: operation_evidence
+            )
+            weights = lane_ids.filter_map do |lane_id|
+              scope = scope_hash(SettingsCascade.lookup(offerings, lane_id), path: "provider.offerings.#{lane_id}")
+              SettingsCascade.lookup(scope, :weight)
+            end
+            return nil if weights.empty?
+
+            unless weights.uniq.length == 1
+              raise ArgumentError, "offering weight scope is ambiguous: the draft's lanes " \
+                                   "#{lane_ids.join(', ')} carry differing configured weights"
+            end
+
+            weights.first
+          end
+
+          def supported_lane_ids(instance_key:, model:, tier:, operation_evidence:)
+            operation_evidence.each_value.with_object([]) do |evidence, lane_ids|
+              next unless evidence.supported?
+
+              lane_id = Identity.compose_lane_id(
+                tier: tier, provider_family: instance_key.provider_family,
+                instance_id: instance_key.instance_id,
+                type: Taxonomies.lane_type_for(operation: evidence.operation), model: model
+              )
+              lane_ids << lane_id unless lane_ids.include?(lane_id)
+            end
+          end
+
+          # nil → default; an explicit 0 passes through (0 = operator disable —
+          # 0 is TRUTHY in Ruby and must not be defaulted); any other non-Integer
+          # RAISES instead of silently applying a different weight.
+          def component(value, default)
+            return default if value.nil?
+
+            raise ArgumentError, "weight component must be an Integer >= 0, got #{value.inspect}" \
+              unless value.is_a?(::Integer) && value >= 0
+
+            value
+          end
+
+          # Missing scope is the identity default. A present malformed scope is
+          # never treated as missing (`false || {}` would silently erase operator
+          # input and recreate a flat identity result).
+          def scope_hash(value, path:)
+            return {} if value.nil?
+            return value if value.is_a?(::Hash)
+
+            raise ArgumentError, "#{path} must be a Hash, got #{value.inspect}"
+          end
+
+          # Pinned return contract: TWO methods. The writer calls both:
+          #   wi = WeightSchema.weight_inputs(...)
+          #   base = WeightSchema.base_weight(wi)
+          def base_weight(weight_inputs)
+            weight_inputs.values.reduce(1, :*)
+          end
+        end
+      end
+    end
+  end
+end