lex-llm-vllm 0.4.5 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb587332ecdb4d2a8e4535d1b03250b3a63e7a8ce5171dc5198c11ad40549bef
-  data.tar.gz: ec906ffff9f3d1a0496a1d0043d25902c08031d6cd613a239847ca97474e4def
+  metadata.gz: d68ddb8f9c969ef5991b7437e6d0d9cea05f2e4dfe9f39fbb9696ec513988b4f
+  data.tar.gz: 9fa21d69ed1c20795872db8648140c4d89b8155487a6def3f0fe7f121bf39e1e
 SHA512:
-  metadata.gz: fd7215d64cda75590f936d6f6a4e39d3669826ee00639e765f426e602cf6a465c61a62bb0655126cb608552d70692eac2469def71a429bb4c885899cb9d9ce95
-  data.tar.gz: 275be07c6a109418995c759a2c9fcf5a67b567cda41335a9bda5e3a0ca723f4cc9fe8436840b04edcdd0f403c1cb7864b475eb407644d22562b1ea64bba22384
+  metadata.gz: 5a372fff3346ff953fe4265073c19cefe72064a2592adb2d8313f2a61241d657424afd1eeb973284d3c15269500c04bcf47b16402317e9c240aebe2c213d62ad
+  data.tar.gz: f2ea87b7809e88965c53c19f412c3c37eb1036a3ffab1cf20bedf60c9c672c6cb918aee3aaf96ee1df513da7815fe287c84ccc8b09808ce6ef96ab5704cc5664

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.4.6] - 2026-08-19
+
+### Changed
+- Publish the immutable four-component lane-weight pair from vLLM discovery and reconcile weight-only changes on the existing module-runner cadence.
+- Serialize initial, recovery, replacement, removal, shutdown, and probe publication transitions behind one module-level mutex without adding a Settings callback or operator workflow.
+- Track configured-but-unpublished weight keys on the ordinary discovery pass and log each dormant transition once.
+- Raise the `lex-llm` dependency floor to 0.7.6; the existing `legion-settings` dependency remains unchanged.
+
+### Fixed
+- Compare the offering catalog as a duplicate-preserving multiset of complete contracts while excluding only non-authoritative evidence observation timestamps, preventing both reorder-only churn and accidental duplicate suppression while retaining real evidence and weight changes.
+- Complete startup discovery and weight validation before constructing a callable or claiming inventory, so malformed settings leave no orphaned initializing scope and the next valid cadence pass recovers without operator action.
+- Use a real in-memory IO sink for the test logger so Ruby 4 cannot fall back to stdout during the file-only RSpec release gate.
+
+### Added
+- Cover the complete writer lifecycle, publication races, failure atomicity, dormant-state cycle, and the actual callable's folded-system OpenAI-compatible wire payload.
+
 ## [0.4.5] - 2026-08-18
 
 ### Fixed

data/lex-llm-vllm.gemspec

@@ -27,8 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.4.2'
   spec.add_dependency 'legion-transport', '>= 1.4.14'
-  # 0.7.1 adds InstanceKey#physical_id (secondary physical identity) — the
-  # discovery runner claims with physical_id:, so the floor must not resolve
-  # to a lex-llm without the field.
-  spec.add_dependency 'lex-llm', '>= 0.7.1'
+  # 0.7.6 carries the write-time weight schema/reconciler and the immutable
+  # OfferingDraft/OfferingRecord/LaneRecord weight pair used by this writer.
+  spec.add_dependency 'lex-llm', '>= 0.7.6'
 end

data/lib/legion/extensions/llm/vllm/helpers/offering_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'legion/extensions/llm/inventory/evidence'
+require 'legion/extensions/llm/inventory/weight_reconciler'
 
 module Legion
   module Extensions
@@ -20,6 +21,13 @@ module Legion
               tier = @instance_cfg[:tier] || :direct
               embed_sup = embedding_supported?(model_data)
               max_output = model_data[:max_output_tokens] || model_data[:max_completion_tokens]
+              weight_inputs = Legion::Extensions::Llm::Inventory::WeightSchema.weight_inputs(
+                settings: Legion::Settings,
+                instance_key: instance_key,
+                provider_native_key: model_id,
+                model: model_id,
+                tier: tier
+              )
 
               Legion::Extensions::Llm::Inventory::OfferingDraft.new(
                 provider_native_key: model_id,
@@ -34,7 +42,9 @@ module Legion
                 tokenizer_evidence: build_tokenizer_evidence(model_data[:tokenizer]),
                 quota_domains: {},
                 metadata: build_metadata(model_data),
-                publication_source: :provider_catalog
+                publication_source: :provider_catalog,
+                weight_inputs: weight_inputs,
+                base_weight: Legion::Extensions::Llm::Inventory::WeightSchema.base_weight(weight_inputs)
               )
             end
 

data/lib/legion/extensions/llm/vllm/runners/discovery_refresh/claim_activation.rb

@@ -31,30 +31,32 @@ module Legion
               # (InstanceKey.instance_id); the derived host:port/ak string is
               # the secondary physical_id (dedup/diagnostics, never identity).
               def claim_and_activate_instance(name:, instance_cfg:)
+                instance_id = name.to_s
                 instance_key = Legion::Extensions::Llm::Inventory::Identity::InstanceKey.new(
-                  provider_family: :vllm, instance_id: name,
+                  provider_family: :vllm, instance_id: instance_id,
                   physical_id: derive_physical_id(instance_cfg: instance_cfg)
                 )
+                offerings = fetch_offerings(instance_cfg: instance_cfg, instance_key: instance_key)
                 callable = Legion::Extensions::Llm::Vllm::VllmCallable.new(instance_cfg: instance_cfg, logger: log)
                 probe_coordinator = Legion::Extensions::Llm::Inventory::ProbeCoordinator.new(
-                  instance_key: instance_key, enqueue: build_probe_enqueue(instance_id: name)
+                  instance_key: instance_key, enqueue: build_probe_enqueue(instance_id: instance_id)
                 )
                 publisher_token = publisher.claim_instance(
-                  instance_id: name, physical_id: instance_key.physical_id,
+                  instance_id: instance_id, physical_id: instance_key.physical_id,
                   callable: callable, probe_request_handle: probe_coordinator
                 )
-
-                # Store state BEFORE readiness so a failed boot probe leaves a
-                # recoverable :initializing entry for the next tick (D4).
                 state = {
-                  name: name, instance_key: instance_key, instance_cfg: instance_cfg,
+                  name: instance_id, instance_key: instance_key, instance_cfg: instance_cfg,
                   callable: callable, probe_coordinator: probe_coordinator,
-                  publisher_token: publisher_token, sequence: 0, offerings: []
+                  publisher_token: publisher_token, sequence: 0, offerings: offerings
                 }
-                instance_states[name] = state
-
-                offerings = fetch_offerings(instance_cfg: instance_cfg, instance_key: instance_key)
-                perform_readiness(instance_id: name, state: state, offerings: offerings)
+                Legion::Extensions::Llm::Inventory::WeightReconciler.track_initializing!(
+                  states: instance_states,
+                  state_key: instance_id,
+                  state: state,
+                  mutex: state_mutex
+                )
+                perform_readiness(instance_id: instance_id, state: state, offerings: offerings)
               end
 
               # Run a readiness probe and commit the outcome. While the instance
@@ -62,7 +64,9 @@ module Legion
               # once activated it reports success/failure against the
               # availability fact.
               def perform_readiness(instance_id:, state:, offerings:)
-                state[:offerings] = offerings
+                reconcile_weight_snapshot(
+                  instance_id: instance_id, state: state, discovered_offerings: offerings
+                )
                 probe_token = publisher.readiness_probe_started(
                   instance_id: instance_id, publisher_token: state[:publisher_token]
                 )
@@ -75,23 +79,43 @@ module Legion
               end
 
               def report_probe_result(instance_id:, state:, probe_token:, readiness:)
-                status = publisher.snapshot.publication_status(instance_key: state[:instance_key])
-                if readiness.ready? && status.state == :initializing
-                  publisher.activate_instance_snapshot(
-                    instance_id: instance_id, publisher_token: state[:publisher_token],
-                    offerings: state[:offerings], sequence: state[:sequence], probe_token: probe_token
-                  )
-                elsif readiness.ready?
-                  publisher.readiness_succeeded(instance_id: instance_id, probe_token: probe_token)
-                else
-                  publisher.readiness_failed(
-                    instance_id: instance_id, probe_token: probe_token, reason: readiness.reason
-                  )
-                end
-                write_instance_health(state)
+                committed = if readiness.ready? && tracked_unpublished?(instance_id: instance_id, state: state)
+                              activate_tracked_state(
+                                instance_id: instance_id, state: state, probe_token: probe_token
+                              )
+                            else
+                              report_tracked_readiness(
+                                instance_id: instance_id, state: state,
+                                probe_token: probe_token, readiness: readiness
+                              )
+                            end
+                write_instance_health(state) if committed
+                committed
               rescue StandardError => e
                 handle_exception(e, level: :warn, operation: 'vllm.runner.discovery.report_probe',
                                     instance_id: instance_id)
+                false
+              end
+
+              def tracked_unpublished?(instance_id:, state:)
+                state_mutex.synchronize do
+                  instance_states[instance_id].equal?(state) && !state.fetch(:published)
+                end
+              end
+
+              def report_tracked_readiness(instance_id:, state:, probe_token:, readiness:)
+                state_mutex.synchronize do
+                  return false unless instance_states[instance_id].equal?(state)
+
+                  if readiness.ready?
+                    publisher.readiness_succeeded(instance_id: instance_id, probe_token: probe_token)
+                  else
+                    publisher.readiness_failed(
+                      instance_id: instance_id, probe_token: probe_token, reason: readiness.reason
+                    )
+                  end
+                  true
+                end
               end
             end
           end

data/lib/legion/extensions/llm/vllm/runners/discovery_refresh/health_display.rb

@@ -15,7 +15,7 @@ module Legion
                 snapshot = publisher.snapshot
                 display = display_fact(instance_key: instance_key, snapshot: snapshot)
 
-                instance_settings = settings.dig(:instances, state[:name])
+                instance_settings = settings.dig(:instances, state[:name].to_sym)
                 return unless instance_settings.is_a?(Hash)
 
                 instance_settings[:health] = health_hash(display)
@@ -26,7 +26,7 @@ module Legion
               end
 
               def clear_settings_health(name:)
-                instance_settings = settings.dig(:instances, name)
+                instance_settings = settings.dig(:instances, name.to_sym)
                 return unless instance_settings.is_a?(Hash)
 
                 instance_settings.delete(:health)

data/lib/legion/extensions/llm/vllm/runners/discovery_refresh/instance_lifecycle.rb

@@ -31,28 +31,36 @@ module Legion
               # names pointing at the same endpoint remain distinct instances.
               def reconcile_instances
                 configured = Vllm.discover_instances
+                configured_ids = configured.keys.map(&:to_s)
 
-                instance_states.each_key do |instance_id|
-                  next if configured.key?(instance_id)
+                tracked_ids = state_mutex.synchronize { instance_states.keys }
+                tracked_ids.each do |instance_id|
+                  next if configured_ids.include?(instance_id)
 
                   remove_instance_state(instance_id)
                 end
 
                 configured.each do |name, instance_cfg|
-                  update_instance(name: name, instance_cfg: instance_cfg)
+                  update_instance(name: name.to_s, instance_cfg: instance_cfg)
                 rescue StandardError => e
                   handle_exception(e, level: :warn, operation: 'vllm.runner.discovery.instance',
                                       instance_name: name.to_s)
                 end
+                observe_dormant_weights
               end
 
               def remove_all_instances(**)
-                instance_states.each_key { |instance_id| remove_instance_state(instance_id) }
+                tracked_ids = state_mutex.synchronize { instance_states.keys }
+                tracked_ids.each { |instance_id| remove_instance_state(instance_id) }
+                state_mutex.synchronize do
+                  instance_states.clear
+                  dormant_weight_tracker.clear!
+                end
                 { success: true }
               end
 
               def update_instance(name:, instance_cfg:)
-                state = instance_states[name]
+                state = state_mutex.synchronize { instance_states[name] }
                 if state && physical_id_changed?(state, instance_cfg)
                   # The physical target moved (endpoint or API key changed) —
                   # the captured callable points at the old endpoint, so drop
@@ -71,10 +79,18 @@ module Legion
               end
 
               def remove_instance_state(instance_id)
-                state = instance_states.delete(instance_id)
+                state = state_mutex.synchronize do
+                  tracked = instance_states[instance_id]
+                  next unless tracked
+
+                  publisher.remove_instance(
+                    instance_id: instance_id, publisher_token: tracked[:publisher_token]
+                  )
+                  instance_states.delete(instance_id) if instance_states[instance_id].equal?(tracked)
+                  tracked
+                end
                 return unless state
 
-                publisher.remove_instance(instance_id: instance_id, publisher_token: state[:publisher_token])
                 clear_settings_health(name: state[:name])
               rescue StandardError => e
                 handle_exception(e, level: :warn, operation: 'vllm.runner.discovery.remove_instance',

data/lib/legion/extensions/llm/vllm/runners/discovery_refresh/offering_comparison.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Vllm
+        module Runners
+          module DiscoveryRefresh
+            # vLLM rebuilds fresh evidence timestamps on every catalog pass.
+            # Compare the complete draft contract while excluding only that
+            # non-authoritative observation telemetry.
+            module OfferingComparison
+              SCALAR_EVIDENCE_FIELDS = %i[
+                context_evidence max_output_evidence embedding_dimensions_evidence
+                model_revision_evidence tokenizer_evidence
+              ].freeze
+
+              def offerings_equivalent?(previous, current)
+                offering_comparison_multiset(previous) == offering_comparison_multiset(current)
+              end
+
+              private
+
+              def offering_comparison_multiset(offerings)
+                Array(offerings).map { |draft| offering_comparison_state(draft) }.tally
+              end
+
+              def offering_comparison_state(draft)
+                state = draft.to_h
+                state[:operation_evidence] = comparison_evidence_map(draft.operation_evidence)
+                state[:capability_evidence] = comparison_evidence_map(draft.capability_evidence)
+                SCALAR_EVIDENCE_FIELDS.each do |field|
+                  state[field] = comparison_evidence(draft.public_send(field))
+                end
+                state
+              end
+
+              def comparison_evidence_map(evidence)
+                evidence.transform_values { |entry| comparison_evidence(entry) }
+              end
+
+              def comparison_evidence(evidence)
+                evidence.to_h.except(:observed_at)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/vllm/runners/discovery_refresh/probing.rb

@@ -10,7 +10,7 @@ module Legion
             # discovery runner. Mixed into DiscoveryRefresh.
             module Probing
               def refresh_instance(instance_id:, instance_cfg:)
-                state = instance_states[instance_id]
+                state = state_mutex.synchronize { instance_states[instance_id] }
                 return unless state
 
                 status = publisher.snapshot.publication_status(instance_key: state[:instance_key])
@@ -29,15 +29,10 @@ module Legion
 
               def replace_if_changed(instance_id:, state:, instance_cfg:)
                 new_offerings = fetch_offerings(instance_cfg: instance_cfg, instance_key: state[:instance_key])
-                return if new_offerings == state[:offerings]
-
-                state[:sequence] += 1
-                publisher.replace_instance_snapshot(
-                  instance_id: instance_id, publisher_token: state[:publisher_token],
-                  offerings: new_offerings, sequence: state[:sequence]
+                changed = reconcile_weight_snapshot(
+                  instance_id: instance_id, state: state, discovered_offerings: new_offerings
                 )
-                state[:offerings] = new_offerings
-                write_instance_health(state)
+                write_instance_health(state) if changed
               end
 
               def run_cadence_probe(instance_id:, state:)
@@ -58,7 +53,7 @@ module Legion
               end
 
               def handle_reactive_probe(instance_id:, request:)
-                state = instance_states[instance_id]
+                state = state_mutex.synchronize { instance_states[instance_id] }
                 return unless state
 
                 coordinator = state[:probe_coordinator]

data/lib/legion/extensions/llm/vllm/runners/discovery_refresh/weight_publication.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Vllm
+        module Runners
+          module DiscoveryRefresh
+            # Module-runner bindings for the shared writer reconciler. The
+            # existing discovery cadence remains the only execution path.
+            module WeightPublication
+              def reconcile_weight_snapshot(instance_id:, state:, discovered_offerings:)
+                Legion::Extensions::Llm::Inventory::WeightReconciler.commit_if_changed!(
+                  settings: Legion::Settings,
+                  instance_id: instance_id,
+                  state: state,
+                  discovered_offerings: discovered_offerings,
+                  mutex: state_mutex,
+                  equivalent: lambda do |previous, current|
+                    !instance_states[instance_id].equal?(state) ||
+                      offerings_equivalent?(previous, current)
+                  end,
+                  replace: method(:replace_weight_snapshot)
+                )
+              end
+
+              def replace_weight_snapshot(instance_id:, state:, offerings:, sequence:)
+                publisher.replace_instance_snapshot(
+                  instance_id: instance_id,
+                  publisher_token: state.fetch(:publisher_token),
+                  offerings: offerings,
+                  sequence: sequence
+                )
+              end
+
+              def activate_weight_snapshot(instance_id:, state:, offerings:, sequence:, probe_token:)
+                publisher.activate_instance_snapshot(
+                  instance_id: instance_id,
+                  publisher_token: state.fetch(:publisher_token),
+                  offerings: offerings,
+                  sequence: sequence,
+                  probe_token: probe_token
+                )
+              end
+
+              def activate_tracked_state(instance_id:, state:, probe_token:)
+                Legion::Extensions::Llm::Inventory::WeightReconciler.activate_tracked!(
+                  settings: Legion::Settings,
+                  instance_id: instance_id,
+                  state_key: state.fetch(:name),
+                  state: state,
+                  states: instance_states,
+                  mutex: state_mutex,
+                  probe_token: probe_token,
+                  activate: method(:activate_weight_snapshot),
+                  activation_sequence: ->(tracked) { tracked.fetch(:sequence) }
+                )
+              end
+
+              def observe_dormant_weights
+                Legion::Extensions::Llm::Inventory::WeightReconciler.observe_dormant!(
+                  settings: Legion::Settings,
+                  provider_family: :vllm,
+                  states: instance_states,
+                  mutex: state_mutex,
+                  tracker: dormant_weight_tracker,
+                  dormant_logger: lambda do |key|
+                    log.info(
+                      "[llm][vllm] action=dormant_weight weight_key=#{key.inspect} no_lane_published=true"
+                    )
+                  end
+                )
+              end
+
+              def state_mutex
+                @state_mutex ||= Mutex.new
+              end
+
+              def dormant_weight_tracker
+                @dormant_weight_tracker ||=
+                  Legion::Extensions::Llm::Inventory::DormantWeightTracker.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/vllm/runners/discovery_refresh.rb

@@ -7,6 +7,8 @@ require 'legion/logging'
 require 'legion/extensions/llm/vllm'
 require 'legion/extensions/llm/inventory/records'
 
+require 'legion/extensions/llm/vllm/runners/discovery_refresh/offering_comparison'
+require 'legion/extensions/llm/vllm/runners/discovery_refresh/weight_publication'
 require 'legion/extensions/llm/vllm/runners/discovery_refresh/instance_lifecycle'
 require 'legion/extensions/llm/vllm/runners/discovery_refresh/claim_activation'
 require 'legion/extensions/llm/vllm/runners/discovery_refresh/probing'
@@ -45,6 +47,8 @@ module Legion
           #   Http              — model/health HTTP, instance identity
           module DiscoveryRefresh
             include Legion::Extensions::Helpers::Lex
+            include OfferingComparison
+            include WeightPublication
             include InstanceLifecycle
             include ClaimActivation
             include Probing
@@ -60,7 +64,10 @@ module Legion
             end
 
             def self.reset_instance_states!
-              @instance_states.clear
+              state_mutex.synchronize do
+                @instance_states.clear
+                dormant_weight_tracker.clear!
+              end
             end
           end
         end

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Vllm
-        VERSION = '0.4.5'
+        VERSION = '0.4.6'
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-vllm
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.6
 platform: ruby
 authors:
 - LegionIO
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.7.1
+        version: 0.7.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.7.1
+        version: 0.7.6
 description: vLLM provider integration for the LegionIO LLM routing framework.
 email:
 - matthewdiverson@gmail.com
@@ -107,7 +107,9 @@ files:
 - lib/legion/extensions/llm/vllm/runners/discovery_refresh/health_display.rb
 - lib/legion/extensions/llm/vllm/runners/discovery_refresh/http.rb
 - lib/legion/extensions/llm/vllm/runners/discovery_refresh/instance_lifecycle.rb
+- lib/legion/extensions/llm/vllm/runners/discovery_refresh/offering_comparison.rb
 - lib/legion/extensions/llm/vllm/runners/discovery_refresh/probing.rb
+- lib/legion/extensions/llm/vllm/runners/discovery_refresh/weight_publication.rb
 - lib/legion/extensions/llm/vllm/runners/fleet_worker.rb
 - lib/legion/extensions/llm/vllm/translator.rb
 - lib/legion/extensions/llm/vllm/version.rb