lex-llm 0.6.16 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ba576c21739b35e60594706468f7a05769871b25e5acd466ae01cbc451eec70
-  data.tar.gz: e0ac7077fdc03270059abe385f202b681928e62d667f0cefad10a0a7d1b79760
+  metadata.gz: b6ab83cce686d4d63038e65c45039320fd61abf117acbde7ea05e4bca8ce1878
+  data.tar.gz: 768282bf56c16956f91a2be653e460e7d961775b8d782ad3177d9a637fb3a032
 SHA512:
-  metadata.gz: 997f024896ce8d0eb54d8574615312c0280efea81ecae75859b3bd702b8dd65aae0fbd5f615801e3e43b9d50cf6079ce4638d9a39488edb7e3a86887ee94a977
-  data.tar.gz: 3a33857e99d99a8f3358e781d46903560cb6932026d6889be2a922e23b865f3c2dacef4e38bd6a34e52af35474eab7f7e935d4c68360a8c56e2758836648d589
+  metadata.gz: b9026c5963387e0c286bcdc80d7dceb61610fc5be4c67acf026b5e3ff59f95475edfdca79fb61f5910e5b143a02b946f36601679acc827fed55f1c998fe4148c
+  data.tar.gz: 2b896edf5d53f9d90c8ac6bdc410b84129d23f50640bd5a981e145d900f097294b3eeb7ffc60d696575a16974a47987eb5d30f8441b55f28041495d80bcc891a

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.7.0 - 2026-08-13
+
+### Added
+- **SSOT v3 provider runtime contract (additive).** A fully typed, process-local inventory and routing contract that lets a migrated provider construct a mandatory `Inventory::InstanceKey`, claim an exact instance for an opaque fenced `PublisherToken`, build immutable `OfferingDraft` values off-registry, run an immediate safe (non-inference) readiness probe, and atomically activate a callable, complete offering snapshot, derived operation lanes, and `available` state only when startup readiness succeeds. Includes:
+  - `Inventory::Identity` with the length-framed SHA-256 `off:v1:`/`lane:v1:` encoders (tier is never an identity input) and binding identity fixtures.
+  - `Inventory` evidence, `OfferingDraft`/`OfferingRecord`/`LaneRecord`/`AvailabilityFact`/`ReadinessResult`/`InstanceRecord`/`PublicationStatus`/`MutationResult` immutable records, `CallableHandle`/`DispatchLease` lifecycle, `PublisherToken`/`ProbeToken`/`ProbeRequest`, `ProbeCoordinator`, and the synchronized `Registry` + generation-tagged `Snapshot`.
+  - `Inventory::Publisher` provider-facing wrapper plus the quarantined post-commit `ScopedRefresher::LegacyCoordinatorAdapter` old-coordinator projection.
+  - `Routing::AttemptTargetKey`/`Selection`/`Rejection`/`Exclusion`/`QuotaDomainKey`/`BodyModelHintDecision` and the provider-neutral `Routing::ProviderOutcome`.
+  - Fail-loud `Provider#speak`/`Provider#translate` base methods (no defaults; `REQUIRED_SIGNATURES` unchanged).
+  - Additive exact-offering fleet execution (`Fleet::Protocol` `exact_offering_v1` marker, signed `execution_contract`/`offering_id`, registry-backed exact dispatch) alongside the unchanged protocol-v2 path.
+  - Shared `'an SSOT v3 provider adapter'` conformance examples consumable by every provider PR.
+
+  The contract adds no dependency on `legion-llm`, LegionIO, a database, ORM, or timer, and preserves every existing provider signature and protocol-v2 fleet behavior. Only the quarantined `ScopedRefresher` retains a direct `Legion::LLM::Inventory` reverse reference (removed in Phase 4).
+
 ## 0.6.16 - 2026-08-04
 
 ### Fixed

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

@@ -10,6 +10,9 @@ module Legion
       # Prerequisites on the extending module:
       #   - `PROVIDER_FAMILY` constant (Symbol, e.g. :ollama)
       #   - `provider_class` singleton method returning the Provider subclass
+      # DEPRECATED (Phase 4 removal): discover_instances/provider_aliases are kept
+      # for old consumers; no new registration side effect is added here. Migrated
+      # provider actors use Inventory::Publisher directly.
       module AutoRegistration
         # Override in each provider.  Returns { instance_id => config_hash }.
         def discover_instances

data/lib/legion/extensions/llm/fleet/protocol.rb

@@ -9,6 +9,18 @@ module Legion
           REQUEST_TYPE = 'llm.fleet.request'
           RESPONSE_TYPE = 'llm.fleet.response'
           ERROR_TYPE = 'llm.fleet.error'
+
+          # Additive exact-execution marker (phase-1-lex-llm-additive.md section 16.1).
+          # An exact request is protocol v2 plus execution_contract == this marker
+          # and a signed offering_id. Marker absence means legacy v2; an unknown
+          # nonempty marker is rejected.
+          EXACT_EXECUTION_CONTRACT = 'exact_offering_v1'
+          EXACT_REQUIRED_FIELDS = %i[
+            execution_contract offering_id provider provider_instance model operation
+          ].freeze
+          EXACT_SIGNED_SCALAR_CLAIMS = %i[
+            execution_contract offering_id
+          ].freeze
         end
       end
     end

data/lib/legion/extensions/llm/fleet/provider_responder.rb

@@ -5,6 +5,7 @@ require 'json'
 require_relative 'protocol'
 require_relative 'settings'
 require_relative 'worker_execution'
+require 'legion/extensions/llm/inventory/registry'
 
 module Legion
   module Extensions
@@ -59,17 +60,19 @@ module Legion
             def reply_to = self[:reply_to]
             def message_context = self[:message_context] || {}
             def trace_context = self[:trace_context] || {}
+            def execution_contract = self[:execution_contract]
+            def offering_id = self[:offering_id]
           end
 
           module_function
 
           # Public runner entry point mirrors AMQP delivery callbacks, which carry both delivery and property metadata.
           # rubocop:disable Metrics/ParameterLists
-          def call(payload:, provider_family:, provider_class:, provider_instances:, delivery: nil, properties: nil)
+          def call(payload:, provider_family:, provider_class:, provider_instances:,
+                   registry: ::Legion::Extensions::Llm::Inventory::Registry, delivery: nil, properties: nil)
             envelope = parse_payload(payload)
             check_envelope!(envelope, provider_family:)
-            provider = build_provider(envelope:, provider_class:, provider_instances:)
-            response = WorkerExecution.call(envelope: envelope, provider: provider)
+            response = dispatch_request(envelope, provider_class, provider_instances, registry)
             publish_response(envelope, response)
             ack(delivery || properties)
             response
@@ -109,6 +112,34 @@ module Legion
 
             validate_protocol_version!(envelope)
             validate_provider_family!(envelope, provider_family)
+            validate_execution_contract!(envelope)
+          end
+
+          # Marker absence means legacy v2; an unknown nonempty marker is rejected;
+          # the exact marker additionally requires every EXACT_REQUIRED_FIELDS value.
+          def validate_execution_contract!(envelope)
+            marker = envelope.execution_contract
+            return if marker.nil?
+            raise ArgumentError, "unknown execution_contract: #{marker}" unless marker == Protocol::EXACT_EXECUTION_CONTRACT
+
+            Protocol::EXACT_REQUIRED_FIELDS.each do |field|
+              raise ArgumentError, "#{field} is required for #{Protocol::EXACT_EXECUTION_CONTRACT}" unless envelope.key?(field) && !envelope[field].nil?
+            end
+          end
+
+          def exact?(envelope)
+            envelope.execution_contract == Protocol::EXACT_EXECUTION_CONTRACT
+          end
+
+          # Exact requests dispatch through the registry and never call
+          # build_provider; legacy v2 keeps the provider-object path.
+          def dispatch_request(envelope, provider_class, provider_instances, registry)
+            if exact?(envelope)
+              WorkerExecution.call(envelope: envelope, registry: registry)
+            else
+              provider = build_provider(envelope:, provider_class:, provider_instances:)
+              WorkerExecution.call(envelope: envelope, provider: provider)
+            end
           end
 
           def build_provider(envelope:, provider_class:, provider_instances:)
@@ -141,7 +172,9 @@ module Legion
               tool_calls: response_field(response, :tool_calls) || [],
               usage: response_usage(response),
               finish_reason: response_field(response, :finish_reason),
-              metadata: response_metadata(response)
+              metadata: response_metadata(response),
+              execution_contract: exact?(envelope) ? envelope.execution_contract : nil,
+              offering_id: exact?(envelope) ? envelope.offering_id : nil
             ).publish
           end
 
@@ -162,7 +195,9 @@ module Legion
               message: error.message,
               error_class: error.class.name,
               retryable: retryable_error?(error),
-              metadata: {}
+              metadata: {},
+              execution_contract: exact?(envelope) ? envelope.execution_contract : nil,
+              offering_id: exact?(envelope) ? envelope.offering_id : nil
             ).publish
           end
 

data/lib/legion/extensions/llm/fleet/token_validator.rb

@@ -3,6 +3,7 @@
 require 'concurrent'
 require 'time'
 
+require_relative 'protocol'
 require_relative 'settings'
 require_relative 'token_error'
 
@@ -91,6 +92,20 @@ module Legion
               actual_hash = claims[hash_key] || content_hash(claims[key])
               raise TokenError, "fleet token #{key} hash mismatch" unless actual_hash == expected_hash
             end
+
+            validate_exact_execution_claims!(claims, envelope)
+          end
+
+          # When the exact-offering marker is present on the envelope, both exact
+          # scalar claims must be signed into the verified JWT and match the
+          # envelope. An unsigned exact marker is never authoritative.
+          def validate_exact_execution_claims!(claims, envelope)
+            return unless envelope[:execution_contract] == Protocol::EXACT_EXECUTION_CONTRACT
+
+            Protocol::EXACT_SIGNED_SCALAR_CLAIMS.each do |key|
+              raise TokenError, "fleet token missing signed #{key}" if claims[key].to_s.empty?
+              raise TokenError, "fleet token #{key} claim mismatch" unless canonical_value(claims[key]) == canonical_value(envelope[key])
+            end
           end
 
           def content_hash(value)

data/lib/legion/extensions/llm/fleet/worker_execution.rb

@@ -2,8 +2,13 @@
 
 require 'concurrent'
 
+require_relative 'protocol'
 require_relative 'settings'
 require_relative 'token_validator'
+require 'legion/extensions/llm/taxonomies'
+require 'legion/extensions/llm/inventory/errors'
+require 'legion/extensions/llm/inventory/identity'
+require 'legion/extensions/llm/inventory/registry'
 
 module Legion
   module Extensions
@@ -21,13 +26,14 @@ module Legion
 
           module_function
 
-          def call(envelope:, provider:)
+          def call(envelope:, registry: nil, provider: nil)
+            validate_dispatch_target!(registry, provider)
             claims = nil
             idempotency_key = nil
             claims = validate_identity!(envelope)
             validate_policy!(envelope)
             idempotency_key = validate_idempotency!(envelope)
-            response = dispatch_local_provider!(envelope: envelope, provider: provider)
+            response = dispatch!(envelope: envelope, registry: registry, provider: provider)
             mark_idempotency_success!(idempotency_key) if idempotency_key
             TokenValidator.mark_replay!(claims[:jti]) if claims.is_a?(Hash)
             response
@@ -87,6 +93,164 @@ module Legion
             end
           end
 
+          ERRORS = Legion::Extensions::Llm::Inventory::Errors
+          IDENTITY = Legion::Extensions::Llm::Inventory::Identity
+
+          def validate_dispatch_target!(registry, provider)
+            return unless registry.nil? == provider.nil?
+
+            raise PolicyError, 'WorkerExecution.call requires exactly one of registry or provider'
+          end
+
+          def dispatch!(envelope:, registry:, provider:)
+            return dispatch_local_provider!(envelope: envelope, provider: provider) if provider
+
+            if envelope_value(envelope, :execution_contract) == Protocol::EXACT_EXECUTION_CONTRACT
+              exact_dispatch!(envelope: envelope, registry: registry)
+            else
+              legacy_registry_dispatch!(envelope: envelope, registry: registry)
+            end
+          end
+
+          # Exact path: resolve by signed offering_id; no model resolution, provider
+          # scan, :default, or first value.
+          def exact_dispatch!(envelope:, registry:)
+            snapshot = registry.snapshot
+            instance_key = exact_instance_key(envelope)
+            record = available_record!(snapshot, instance_key)
+            offering = record.offerings_by_id[envelope_value(envelope, :offering_id)]
+            raise ERRORS::ExactOfferingMismatchError, 'offering_id not on the activated instance' if offering.nil?
+
+            operation = exact_operation(envelope)
+            model = require_matching_model!(offering, envelope)
+            require_supported!(offering, operation)
+            execute_via_lane(registry, snapshot,
+                             { record: record, offering: offering, operation: operation, model: model, envelope: envelope })
+          end
+
+          # Registry-backed v2 compatibility path for a migrated provider: execute
+          # only when (provider_family, instance, operation, model) resolves to
+          # exactly one supported local offering.
+          def legacy_registry_dispatch!(envelope:, registry:)
+            snapshot = registry.snapshot
+            instance_key = exact_instance_key(envelope)
+            record = available_record!(snapshot, instance_key)
+            operation = Legion::Extensions::Llm::Taxonomies.normalize_operation(value: envelope_value(envelope, :operation), allow_aliases: true)
+            model = IDENTITY.normalize_text(value: envelope_value(envelope, :model), field: :model)
+            matches = record.offerings_by_id.values.select { |o| o.model == model && o.operation_status(operation: operation) == :supported }
+            raise ERRORS::ExactOfferingMismatchError, 'no matching local offering' if matches.empty?
+            raise ERRORS::AmbiguousLegacyOfferingError, 'multiple matching local offerings' if matches.size > 1
+
+            execute_via_lane(registry, snapshot,
+                             { record: record, offering: matches.first, operation: operation, model: model, envelope: envelope })
+          end
+
+          def execute_via_lane(registry, snapshot, resolution)
+            lane = matching_lane!(snapshot, resolution[:record], resolution[:offering], resolution[:operation], resolution[:model])
+            lease = registry.acquire(callable_handle: lane.callable_handle)
+            begin
+              dispatch_operation(lease.callable, resolution[:operation], resolution[:model], exact_params(resolution[:envelope]))
+            ensure
+              lease.release
+            end
+          end
+
+          def exact_instance_key(envelope)
+            IDENTITY::InstanceKey.new(
+              provider_family: envelope_value(envelope, :provider), instance_id: envelope_value(envelope, :provider_instance)
+            )
+          end
+
+          def available_record!(snapshot, instance_key)
+            record = snapshot.instance(instance_key: instance_key)
+            raise ERRORS::ExactOfferingMismatchError, 'instance is absent, initializing, or unavailable' unless record && record.availability.state == :available
+
+            record
+          end
+
+          def exact_operation(envelope)
+            Legion::Extensions::Llm::Taxonomies.normalize_operation(value: envelope_value(envelope, :operation), allow_aliases: false)
+          end
+
+          def require_matching_model!(offering, envelope)
+            model = IDENTITY.normalize_text(value: envelope_value(envelope, :model), field: :model)
+            raise ERRORS::ExactOfferingMismatchError, 'model does not match the offering' unless offering.model == model
+
+            model
+          end
+
+          def require_supported!(offering, operation)
+            return if offering.operation_status(operation: operation) == :supported
+
+            raise ERRORS::ExactOfferingMismatchError, "operation #{operation} is not supported by the offering"
+          end
+
+          def matching_lane!(snapshot, record, offering, operation, model)
+            lane_id = IDENTITY.lane_id(instance_key: record.instance_key, operation: operation, model: model, offering_id: offering.offering_id)
+            lane = snapshot.lane(lane_id: lane_id)
+            valid = lane && lane.offering_id == offering.offering_id && lane.instance_key == record.instance_key &&
+                    lane.model == model && lane.operation == operation && lane.callable_handle.equal?(record.callable_handle)
+            raise ERRORS::ExactOfferingMismatchError, 'no matching lane for the offering' unless valid
+
+            lane
+          end
+
+          def exact_params(envelope)
+            raw = envelope_value(envelope, :params) || {}
+            params = {}
+            raw.each do |key, value|
+              sym = key.respond_to?(:to_sym) ? key.to_sym : key
+              raise ERRORS::ExactOfferingMismatchError, "duplicate param spelling for #{sym}" if params.key?(sym)
+
+              params[sym] = value
+            end
+            raise ERRORS::ExactOfferingMismatchError, 'params must not contain model' if params.key?(:model)
+
+            params
+          end
+
+          def dispatch_operation(callable, operation, model, params)
+            case operation
+            when :chat then callable.chat(messages: require_param!(params, :messages, operation), model: model, **except(params, :messages))
+            when :stream_chat then callable.stream_chat(messages: require_param!(params, :messages, operation), model: model, **except(params, :messages))
+            when :count_tokens then callable.count_tokens(messages: require_param!(params, :messages, operation), model: model, **except(params, :messages))
+            when :embed then callable.embed(text: require_param!(params, :text, operation), model: model, **except(params, :text))
+            when :image then dispatch_image(callable, model, params)
+            when :transcribe then dispatch_audio(callable, :transcribe, model, params)
+            when :translate then dispatch_audio(callable, :translate, model, params)
+            when :speak then dispatch_speak(callable, model, params)
+            when :moderate then callable.moderate(require_param!(params, :input, operation), model: model, **except(params, :input))
+            else raise ERRORS::ExactOfferingMismatchError, "unsupported exact operation: #{operation}"
+            end
+          end
+
+          def dispatch_image(callable, model, params)
+            require_param!(params, :prompt, :image)
+            require_param!(params, :size, :image)
+            callable.image(prompt: params[:prompt], model: model, **except(params, :prompt))
+          end
+
+          def dispatch_audio(callable, operation, model, params)
+            require_param!(params, :audio_file, operation)
+            raise ERRORS::ExactOfferingMismatchError, "#{operation} requires the language key" unless params.key?(:language)
+
+            callable.public_send(
+              operation, params[:audio_file], model: model, language: params[:language],
+                                              **except(params, :audio_file, :model, :language)
+            )
+          end
+
+          def dispatch_speak(callable, model, params)
+            require_param!(params, :text, :speak)
+            callable.speak(params[:text], model: model, voice: params[:voice], **except(params, :text, :model, :voice))
+          end
+
+          def require_param!(params, key, operation)
+            raise ERRORS::ExactOfferingMismatchError, "#{operation} requires the #{key} param" unless params.key?(key)
+
+            params[key]
+          end
+
           def unpack_legacy_options(params)
             options = params.delete(:options)
             return params unless options.is_a?(Hash)

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/logging'
+require 'legion/extensions/llm/inventory/errors'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # A dispatch lease over a CallableHandle. Holds the exact provider
+        # callable for one in-flight request and releases the reference exactly
+        # once. See phase-1-lex-llm-additive.md section 11.4.
+        class DispatchLease
+          attr_reader :lease_id, :callable
+
+          def initialize(lease_id:, callable_handle:, callable:)
+            @lease_id = lease_id.dup.freeze
+            @callable_handle = callable_handle
+            @callable = callable
+            @released = false
+          end
+
+          def released?
+            @released
+          end
+
+          def release
+            @callable_handle.__send__(:release_lease, self)
+          end
+
+          private
+
+          # Set only by the owning CallableHandle under its private Mutex.
+          def mark_released!
+            @released = true
+          end
+        end
+
+        # Owns the acquire/retire lifecycle for one provider callable. The
+        # handle's object identity is stable while its state moves
+        # ACTIVE -> RETIRING -> DISPOSED under a private Mutex. Retiring an old
+        # handle cannot disconnect a distinct new callable because a new claim
+        # must supply a distinct callable object. See section 11.4.
+        class CallableHandle
+          include Legion::Logging::Helper
+
+          attr_reader :handle_id
+
+          def initialize(handle_id:, callable:)
+            raise Errors::ValidationError, 'handle_id must be a non-empty String' unless nonempty_string?(handle_id)
+            raise Errors::ValidationError, 'callable must not be nil' if callable.nil?
+
+            @handle_id = handle_id.dup.freeze
+            @callable = callable
+            @state = :active
+            @reference_count = 0
+            @disposed_with_error = false
+            @mutex = Mutex.new
+          end
+
+          def state
+            @mutex.synchronize { @state }
+          end
+
+          def reference_count
+            @mutex.synchronize { @reference_count }
+          end
+
+          def acquire
+            @mutex.synchronize do
+              case @state
+              when :retiring
+                raise Errors::StaleCallableError, "callable handle #{@handle_id} is retiring"
+              when :disposed
+                raise Errors::CallableDisposedError, "callable handle #{@handle_id} is disposed"
+              end
+
+              @reference_count += 1
+              DispatchLease.new(
+                lease_id: "lease:v1:#{SecureRandom.uuid}", callable_handle: self, callable: @callable
+              )
+            end
+          end
+
+          def retire
+            @mutex.synchronize do
+              case @state
+              when :disposed
+                return @disposed_with_error ? :disposed_with_error : :disposed
+              when :retiring
+                return :retiring
+              end
+
+              @state = :retiring
+              return :retiring if @reference_count.positive?
+
+              dispose_locked
+            end
+          end
+
+          private
+
+          def release_lease(lease)
+            @mutex.synchronize do
+              raise Errors::InvalidTransitionError, 'dispatch lease already released' if lease.released?
+
+              lease.__send__(:mark_released!)
+              @reference_count -= 1
+              dispose_locked if @reference_count.zero? && @state == :retiring
+              nil
+            end
+          end
+
+          # Caller must hold @mutex. Calls disconnect exactly once and transitions
+          # to DISPOSED even when disconnect raises.
+          def dispose_locked
+            callable = @callable
+            callable_class = callable.class.name
+            @callable = nil
+            begin
+              callable.disconnect
+              @state = :disposed
+              :disposed
+            rescue StandardError => e
+              @disposed_with_error = true
+              @state = :disposed
+              handle_exception(
+                e, handled: true, level: :warn,
+                   operation: 'llm.inventory.callable_handle.dispose',
+                   handle_id: @handle_id, callable_class: callable_class
+              )
+              :disposed_with_error
+            end
+          end
+
+          def nonempty_string?(value)
+            value.is_a?(::String) && !value.strip.empty?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # Typed contract/validation/fencing/transition/acquisition errors for the
+        # SSOT v3 runtime contract. See phase-1-lex-llm-additive.md section 7.
+        #
+        # ValidationError descends from ArgumentError because it signals a caller
+        # supplying an invalid field; every other error descends from Error so a
+        # consumer can rescue the whole inventory family with one class.
+        #
+        # Validation errors identify the invalid field but never include
+        # credentials, raw endpoints containing secrets, callable inspection, or
+        # publisher tokens.
+        module Errors
+          class Error < StandardError; end
+          class ValidationError < ArgumentError; end
+          class UnknownInstanceError < Error; end
+          class FencedPublisherError < Error; end
+          class StaleSequenceError < Error; end
+          class InvalidProbeError < Error; end
+          class InvalidTransitionError < Error; end
+          class UnknownCallableError < Error; end
+          class StaleCallableError < Error; end
+          class CallableDisposedError < Error; end
+          class ExactOfferingMismatchError < Error; end
+          class AmbiguousLegacyOfferingError < Error; end
+        end
+      end
+    end
+  end
+end