lex-llm 0.7.6 → 0.8.4

data/spec/legion/extensions/llm/fleet/worker_execution_spec.rb

@@ -1,80 +1,88 @@
 # frozen_string_literal: true
 
+require 'spec_helper'
 require 'legion/extensions/llm/fleet/worker_execution'
+require 'support/ssot_registry_helpers'
 
 RSpec.describe Legion::Extensions::Llm::Fleet::WorkerExecution do
+  include SsotRegistryHelpers
+
+  let(:key) { instance_key(family: 'vllm', instance: 'h200') }
+  let(:callable) do
+    Class.new do
+      attr_reader :dispatched
+
+      def initialize
+        @dispatched = []
+      end
+
+      def chat(messages, model:, **rest)
+        @dispatched << { operation: :chat, model: model, first: messages.first, rest: rest }
+        Legion::Extensions::Llm::Canonical::Response.build(text: "#{model}:#{messages.first.text}", model: model)
+      end
+    end.new
+  end
   let(:envelope) do
     {
-      operation: :chat,
-      model: 'llama3',
+      request_id: 'req-1',
+      correlation_id: 'corr-1',
+      idempotency_key: 'idem-1',
+      operation: 'chat',
+      provider: 'vllm',
+      provider_instance: 'h200',
+      model: 'gemma4',
       params: { messages: [{ role: 'user', content: 'hello' }] },
+      reply_to: 'reply.1',
+      message_context: {},
+      caller: 'e2e',
+      trace_context: {},
       signed_token: 'unsigned',
-      idempotency_key: 'idem-1'
+      timeout_seconds: 30,
+      expires_at: (Time.now + 120).utc.iso8601,
+      protocol_version: Legion::Extensions::Llm::Fleet::Protocol::VERSION,
+      execution_contract: Legion::Extensions::Llm::Fleet::Protocol::EXACT_EXECUTION_CONTRACT,
+      offering_id: Legion::Extensions::Llm::Inventory::Registry.snapshot
+                                                               .lanes_for(instance_key: key).first.lane_id
     }
   end
-  let(:provider) do
-    Class.new do
-      def chat(messages:, model:, **)
-        { content: "#{model}:#{messages.first[:content]}" }
-      end
-    end.new
+
+  def activate!
+    claim_and_activate(key: key, callable: callable, coordinator: probe_coordinator(key), model: 'gemma4')
   end
 
   before do
+    Legion::Extensions::Llm::Inventory::Registry.reset!
+    activate!
     described_class.reset_idempotency_cache!
     allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value).and_call_original
     allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
       .with(:fleet, :auth, :require_signed_token, default: true).and_return(false)
-  end
-
-  it 'dispatches canonical chat operations directly to the local provider' do
     allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
       .with(:fleet, :responder, :require_idempotency, default: nil).and_return(false)
+  end
+
+  it 'executes the exact request against the captured registry callable (W1/W2)' do
+    response = described_class.call(envelope: envelope, registry: registry)
 
-    expect(described_class.call(envelope: envelope, provider: provider)).to eq(content: 'llama3:hello')
+    expect(response).to be_a(Legion::Extensions::Llm::Canonical::Response)
+    expect(response.text).to eq('gemma4:hello')
+    expect(callable.dispatched.first[:first]).to be_a(Legion::Extensions::Llm::Canonical::Message)
   end
 
-  it 'unpacks legacy nested options before dispatching to the local provider' do
-    allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
-      .with(:fleet, :responder, :require_idempotency, default: nil).and_return(false)
-    captured_options = nil
-    capture_provider = Class.new do
-      define_method(:chat) do |messages:, model:, **options|
-        captured_options = options
-        { content: "#{model}:#{messages.first[:content]}" }
-      end
-    end.new
-    legacy_envelope = envelope.merge(
-      params: {
-        messages: [{ role: 'user', content: 'hello' }],
-        stream: false,
-        tools: { current: { name: 'current' } },
-        options: {
-          'stream' => true,
-          'system' => 'Use available tools.',
-          'tools' => { legacy: { name: 'legacy' } }
-        }
-      }
-    )
-
-    described_class.call(envelope: legacy_envelope, provider: capture_provider)
-
-    expect(captured_options).to include(
-      stream: false,
-      system: 'Use available tools.',
-      tools: { current: { name: 'current' } }
-    )
-    expect(captured_options).not_to have_key(:options)
+  it 'requires registry — the provider-object topology is deleted (W1)' do
+    expect { described_class.call(envelope: envelope, registry: nil) }
+      .to raise_error(described_class::PolicyError, /requires registry/)
+    expect(described_class.method(:call).parameters).to eq([%i[keyreq envelope], %i[keyreq registry]])
   end
 
-  it 'rejects duplicate idempotency keys before executing the provider again' do
+  it 'rejects duplicate idempotency keys before executing the callable again (W7)' do
     allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
       .with(:fleet, :responder, :require_idempotency, default: nil).and_return(true)
 
-    described_class.call(envelope: envelope, provider: provider)
+    described_class.call(envelope: envelope, registry: registry)
 
     expect do
-      described_class.call(envelope: envelope, provider: provider)
+      described_class.call(envelope: envelope, registry: registry)
     end.to raise_error(described_class::PolicyError, /duplicate fleet idempotency key/)
   end
 
@@ -91,58 +99,69 @@ RSpec.describe Legion::Extensions::Llm::Fleet::WorkerExecution do
     end.to raise_error(described_class::PolicyError, /duplicate fleet idempotency key/)
   end
 
-  it 'reserves token replay protection before provider dispatch and marks success after completion' do
+  it 'reserves token replay before dispatch and marks success after (S4)' do
     allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
       .with(:fleet, :auth, :require_signed_token, default: true).and_return(true)
-    allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
-      .with(:fleet, :responder, :require_idempotency, default: nil).and_return(false)
     allow(Legion::Extensions::Llm::Fleet::TokenValidator).to receive(:validate!).and_return({ jti: 'jti-1' })
     allow(Legion::Extensions::Llm::Fleet::TokenValidator).to receive(:mark_replay!)
 
-    described_class.call(envelope: envelope, provider: provider)
+    described_class.call(envelope: envelope, registry: registry)
 
-    expect(Legion::Extensions::Llm::Fleet::TokenValidator).to have_received(:validate!)
-      .with(token: 'unsigned', envelope: envelope)
     expect(Legion::Extensions::Llm::Fleet::TokenValidator).to have_received(:mark_replay!).with('jti-1')
   end
 
-  it 'releases reserved token replay state when provider dispatch fails' do
-    failing_provider = Class.new do
-      def chat(**)
-        raise 'provider unavailable'
-      end
-    end.new
+  it 'releases reserved replay state when dispatch fails (S4)' do
+    failing_callable = Class.new { def chat(*, **) = raise('provider unavailable') }.new
+    key2 = instance_key(family: 'vllm', instance: 'h201')
+    claim_and_activate(key: key2, callable: failing_callable, coordinator: probe_coordinator(key2), model: 'gemma4')
+    failing_envelope = envelope.merge(provider_instance: 'h201',
+                                      offering_id: Legion::Extensions::Llm::Inventory::Registry.snapshot
+                                                                                               .lanes_for(instance_key: key2).first.lane_id)
     allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
       .with(:fleet, :auth, :require_signed_token, default: true).and_return(true)
-    allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
-      .with(:fleet, :responder, :require_idempotency, default: nil).and_return(false)
     allow(Legion::Extensions::Llm::Fleet::TokenValidator).to receive(:validate!).and_return({ jti: 'jti-2' })
     allow(Legion::Extensions::Llm::Fleet::TokenValidator).to receive(:release_replay!)
 
     expect do
-      described_class.call(envelope: envelope, provider: failing_provider)
+      described_class.call(envelope: failing_envelope, registry: registry)
     end.to raise_error(RuntimeError, /provider unavailable/)
 
     expect(Legion::Extensions::Llm::Fleet::TokenValidator).to have_received(:release_replay!).with('jti-2')
   end
 
-  describe '.envelope_value' do
-    it 'preserves false values for both key spellings' do
-      expect(described_class.envelope_value({ execution_contract: false }, :execution_contract)).to be(false)
-      expect(described_class.envelope_value({ 'execution_contract' => false }, :execution_contract)).to be(false)
+  describe 'W5/W4 — params and wire-message contract errors' do
+    it 'raises ContractError when params contain :model' do
+      bad = envelope.merge(params: { messages: [{ role: 'user', content: 'x' }], model: 'other' })
+      expect { described_class.call(envelope: bad, registry: registry) }
+        .to raise_error(Legion::Extensions::Llm::Fleet::ContractError, /must not contain model/)
     end
 
-    it 'prefers a present symbol key even when its value is false' do
-      mixed = { execution_contract: false, 'execution_contract' => 'exact_offering_v1' }
+    it 'raises ContractError on a non-Hash wire message' do
+      bad = envelope.merge(params: { messages: ['not a message'] })
+      expect { described_class.call(envelope: bad, registry: registry) }
+        .to raise_error(Legion::Extensions::Llm::Fleet::ContractError, /serialized Canonical::Message/)
+    end
 
-      expect(described_class.envelope_value(mixed, :execution_contract)).to be(false)
+    it 'raises ContractError on a missing per-operation param' do
+      bad = envelope.merge(params: {})
+      expect { described_class.call(envelope: bad, registry: registry) }
+        .to raise_error(Legion::Extensions::Llm::Fleet::ContractError, /requires the messages param/)
     end
 
-    it 'preserves legacy absence and nil while returning the exact marker unchanged' do
-      expect(described_class.envelope_value({}, :execution_contract)).to be_nil
-      expect(described_class.envelope_value({ execution_contract: nil }, :execution_contract)).to be_nil
-      expect(described_class.envelope_value({ execution_contract: 'exact_offering_v1' }, :execution_contract))
-        .to eq('exact_offering_v1')
+    it 'raises ContractError on an unknown operation' do
+      bad = envelope.merge(operation: 'teleport')
+      expect { described_class.call(envelope: bad, registry: registry) }
+        .to raise_error(Legion::Extensions::Llm::Fleet::ContractError, /unsupported exact operation/)
+    end
+  end
+
+  describe 'W6 — fail-closed policy' do
+    it 'raises when require_policy is enabled and no policy engine exists' do
+      allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
+        .with(:fleet, :responder, :require_policy, default: nil).and_return(true)
+
+      expect { described_class.call(envelope: envelope, registry: registry) }
+        .to raise_error(described_class::PolicyError, /no policy engine is configured/)
     end
   end
 end

data/spec/legion/extensions/llm/fleet_messages_spec.rb

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-# rubocop:disable RSpec/DescribeClass
+# rubocop:disable-next RSpec/DescribeClass
 RSpec.describe 'LLM fleet message envelopes' do
   let(:protocol) { Legion::Extensions::Llm::Fleet::Protocol }
   let(:channel_class) do
@@ -20,6 +20,7 @@ RSpec.describe 'LLM fleet message envelopes' do
       routing_key: 'llm.fleet.inference.qwen.ctx8192',
       request_id: 'req-1',
       correlation_id: 'corr-1',
+      idempotency_key: 'idem-1',
       operation: :chat,
       provider: :vllm,
       provider_instance: :apollo,
@@ -33,21 +34,64 @@ RSpec.describe 'LLM fleet message envelopes' do
       timeout_seconds: 30,
       expires_at: '2026-05-06T12:00:30Z',
       protocol_version: protocol::VERSION,
-      idempotency_key: 'idem-1'
+      execution_contract: protocol::EXACT_EXECUTION_CONTRACT,
+      offering_id: 'local:vllm:h200:inference:gemma4'
+    }
+  end
+
+  def valid_response_options
+    {
+      protocol_version: protocol::VERSION,
+      request_id: 'req-1',
+      correlation_id: 'corr-1',
+      idempotency_key: 'idem-1',
+      operation: :chat,
+      provider: :vllm,
+      provider_instance: :apollo,
+      model: 'qwen',
+      reply_to: 'llm.fleet.reply.node',
+      message_context: { conversation_id: 'conv-1' },
+      trace_context: { trace_id: 'trace-1' },
+      response: { text: 'hello', stop_reason: :end_turn, usage: { input_tokens: 1, output_tokens: 2 } },
+      execution_contract: protocol::EXACT_EXECUTION_CONTRACT,
+      offering_id: 'local:vllm:h200:inference:gemma4'
     }
   end
 
   describe Legion::Extensions::Llm::Fleet::Protocol do
-    it 'defines fleet protocol v2 message types' do
-      expect(described_class::VERSION).to eq(2)
+    it 'defines fleet protocol v3 with the one required-field list (P1/E2)' do
+      expect(described_class::VERSION).to eq(3)
       expect(described_class::REQUEST_TYPE).to eq('llm.fleet.request')
       expect(described_class::RESPONSE_TYPE).to eq('llm.fleet.response')
       expect(described_class::ERROR_TYPE).to eq('llm.fleet.error')
+      expect(described_class::REQUIRED_FIELDS).to include(
+        :request_id, :correlation_id, :idempotency_key, :operation, :provider, :provider_instance,
+        :model, :params, :reply_to, :message_context, :caller, :trace_context, :signed_token,
+        :timeout_seconds, :expires_at, :protocol_version, :execution_contract, :offering_id
+      )
+      expect(described_class::LEGACY_FIELDS).to eq(%i[schema_version request_type fleet_correlation_id])
+    end
+  end
+
+  describe Legion::Extensions::Llm::Fleet::FleetEnvelope do
+    let(:envelope_class) { described_class }
+
+    it 'wraps a Hash payload and passes an existing envelope through' do
+      expect(envelope_class.wrap(a: 1).to_h).to eq(a: 1)
+      envelope = envelope_class.new(data: { b: 2 })
+      expect(envelope_class.wrap(envelope)).to be(envelope)
+    end
+
+    it 'L12: a non-Hash payload is a typed ContractError at the wrap boundary' do
+      expect { envelope_class.wrap('not a hash') }
+        .to raise_error(Legion::Extensions::Llm::Fleet::ContractError, /expected Hash, got String/)
+      expect { envelope_class.wrap(42) }
+        .to raise_error(Legion::Extensions::Llm::Fleet::ContractError, /expected Hash, got Integer/)
     end
   end
 
   describe Legion::Extensions::Llm::Transport::Messages::FleetRequest do
-    it 'builds a strict protocol v2 request envelope' do
+    it 'builds a strict protocol v3 request envelope' do
       message = described_class.new(**valid_request_options)
 
       expect(message.type).to eq(protocol::REQUEST_TYPE)
@@ -55,7 +99,7 @@ RSpec.describe 'LLM fleet message envelopes' do
       expect(message.reply_to).to eq('llm.fleet.reply.node')
       expect(message.correlation_id).to eq('corr-1')
       expect(message.message).to include(
-        protocol_version: 2,
+        protocol_version: 3,
         request_id: 'req-1',
         correlation_id: 'corr-1',
         operation: :chat,
@@ -70,16 +114,15 @@ RSpec.describe 'LLM fleet message envelopes' do
         signed_token: 'signed.jwt',
         timeout_seconds: 30,
         expires_at: '2026-05-06T12:00:30Z',
-        idempotency_key: 'idem-1'
+        idempotency_key: 'idem-1',
+        execution_contract: protocol::EXACT_EXECUTION_CONTRACT,
+        offering_id: 'local:vllm:h200:inference:gemma4'
       )
       expect(message.message).not_to include(:schema_version, :request_type, :fleet_correlation_id)
     end
 
-    it 'requires every protocol v2 request field' do
-      required = %i[
-        request_id correlation_id operation provider provider_instance model params reply_to
-        message_context caller trace_context signed_token timeout_seconds expires_at protocol_version idempotency_key
-      ]
+    it 'requires every protocol v3 request field (one Protocol list, E2)' do
+      required = protocol::REQUIRED_FIELDS + %i[routing_key]
 
       required.each do |field|
         expect do
@@ -88,10 +131,16 @@ RSpec.describe 'LLM fleet message envelopes' do
       end
     end
 
-    it 'rejects protocol versions other than v2' do
+    it 'rejects protocol versions other than v3' do
+      expect do
+        described_class.new(**valid_request_options, protocol_version: 2)
+      end.to raise_error(ArgumentError, /protocol_version must be 3/)
+    end
+
+    it 'rejects a missing protocol_version (P3 — no default fill)' do
       expect do
-        described_class.new(**valid_request_options, protocol_version: 1)
-      end.to raise_error(ArgumentError, /protocol_version/)
+        described_class.new(**valid_request_options.except(:protocol_version))
+      end.to raise_error(ArgumentError, /protocol_version is required/)
     end
 
     it 'rejects legacy fleet envelope fields' do
@@ -141,9 +190,9 @@ RSpec.describe 'LLM fleet message envelopes' do
         name: 'llm.fleet',
         channel: channel
       )
-      allow(channel).to receive(:confirm_select)
       message = described_class.new(**valid_request_options)
 
+      allow(channel).to receive(:confirm_select)
       allow(Legion::Extensions::Llm::Transport::Exchanges::Fleet).to receive(:cached_instance).and_return(exchange)
       result = message.publish(publish_confirm_timeout_ms: 5000)
 
@@ -154,26 +203,14 @@ RSpec.describe 'LLM fleet message envelopes' do
   end
 
   describe Legion::Extensions::Llm::Transport::Messages::FleetResponse do
-    it 'builds a protocol v2 correlated response envelope' do
-      message = described_class.new(
-        request_id: 'req-1',
-        correlation_id: 'corr-1',
-        idempotency_key: 'idem-1',
-        operation: :chat,
-        reply_to: 'llm.fleet.reply.node',
-        provider: :vllm,
-        provider_instance: :apollo,
-        model: 'qwen',
-        content: 'hello',
-        message_context: { conversation_id: 'conv-1' },
-        trace_context: { trace_id: 'trace-1' }
-      )
+    it 'builds a protocol v3 correlated response envelope carrying the serialized Canonical::Response (E3)' do
+      message = described_class.new(**valid_response_options)
 
       expect(message.type).to eq(protocol::RESPONSE_TYPE)
       expect(message.routing_key).to eq('llm.fleet.reply.node')
       expect(message.correlation_id).to eq('corr-1')
       expect(message.message).to include(
-        protocol_version: 2,
+        protocol_version: 3,
         request_id: 'req-1',
         correlation_id: 'corr-1',
         idempotency_key: 'idem-1',
@@ -182,62 +219,48 @@ RSpec.describe 'LLM fleet message envelopes' do
         provider: :vllm,
         provider_instance: :apollo,
         model: 'qwen',
-        content: 'hello',
-        message_context: { conversation_id: 'conv-1' },
-        trace_context: { trace_id: 'trace-1' }
+        response: { text: 'hello', stop_reason: :end_turn, usage: { input_tokens: 1, output_tokens: 2 } },
+        execution_contract: protocol::EXACT_EXECUTION_CONTRACT,
+        offering_id: 'local:vllm:h200:inference:gemma4'
       )
-      expect(message.message).not_to include(:schema_version)
+      expect(message.message).not_to include(:schema_version, :content, :usage, :finish_reason, :tool_calls, :instance)
     end
 
-    it 'includes execution_contract and offering_id only for an exact request' do
-      exact = described_class.new(
-        request_id: 'req-1', correlation_id: 'corr-1', reply_to: 'llm.fleet.reply.node', content: 'hi',
-        execution_contract: 'exact_offering_v1', offering_id: 'off:v1:abc'
-      )
-      expect(exact.message).to include(execution_contract: 'exact_offering_v1', offering_id: 'off:v1:abc')
-
-      legacy = described_class.new(
-        request_id: 'req-1', correlation_id: 'corr-1', reply_to: 'llm.fleet.reply.node', content: 'hi'
-      )
-      expect(legacy.message).not_to have_key(:execution_contract)
-      expect(legacy.message).not_to have_key(:offering_id)
+    it 'requires the response payload and a protocol version' do
+      expect do
+        described_class.new(**valid_response_options.except(:response))
+      end.to raise_error(ArgumentError, /response is required/)
+      expect do
+        described_class.new(**valid_response_options.except(:protocol_version))
+      end.to raise_error(ArgumentError, /protocol_version is required/)
     end
 
-    it 'rejects response protocol versions other than v2' do
+    it 'rejects response protocol versions other than v3' do
       expect do
-        described_class.new(
-          request_id: 'req-1',
-          correlation_id: 'corr-1',
-          reply_to: 'llm.fleet.reply.node',
-          content: 'hello',
-          protocol_version: 1
-        )
-      end.to raise_error(ArgumentError, /protocol_version/)
+        described_class.new(**valid_response_options, protocol_version: 2)
+      end.to raise_error(ArgumentError, /protocol_version must be 3/)
     end
 
-    it 'does not expose thinking in caller-visible response payloads' do
-      message = described_class.new(
-        request_id: 'req-1',
-        correlation_id: 'corr-1',
-        reply_to: 'llm.fleet.reply.node',
-        content: 'visible',
-        thinking: 'hidden'
-      )
+    it 'is a pass-through for the response payload — the G5 thinking exclusion happens exactly once at the responder builder' do
+      message = described_class.new(**valid_response_options, response: { text: 'visible', stop_reason: :end_turn })
 
-      expect(message.message).to include(content: 'visible')
+      expect(message.message[:response]).to eq(text: 'visible', stop_reason: :end_turn)
       expect(message.message).not_to have_key(:thinking)
-      expect(message.encode_message).not_to include('hidden', 'thinking')
+      expect(message.encode_message).not_to include('thinking')
+    end
+
+    it 'rejects legacy fleet envelope fields' do
+      %i[schema_version request_type fleet_correlation_id].each do |field|
+        expect do
+          described_class.new(**valid_response_options, field => 'legacy')
+        end.to raise_error(ArgumentError, /#{field}/)
+      end
     end
 
     it 'publishes replies through the AMQP default exchange without confirms or mandatory routing' do
       default_exchange = instance_double(Bunny::Exchange, publish: true)
       channel = instance_double(Bunny::Channel, default_exchange: default_exchange)
-      message = described_class.new(
-        request_id: 'req-1',
-        correlation_id: 'corr-1',
-        reply_to: 'llm.fleet.reply.node',
-        content: 'hello'
-      )
+      message = described_class.new(**valid_response_options)
 
       allow(message).to receive(:channel).and_return(channel)
       message.publish
@@ -257,12 +280,7 @@ RSpec.describe 'LLM fleet message envelopes' do
       channel = instance_double(channel_class, default_exchange: nil, on_return: nil)
       default_exchange = instance_double(Bunny::Exchange, publish: true, name: 'default', channel: channel)
       allow(channel).to receive(:default_exchange).and_return(default_exchange)
-      message = described_class.new(
-        request_id: 'req-1',
-        correlation_id: 'corr-1',
-        reply_to: 'llm.fleet.reply.node',
-        content: 'hello'
-      )
+      message = described_class.new(**valid_response_options)
 
       allow(message).to receive(:channel).and_return(channel)
       result = message.publish(return_result: true, headers: { 'x-custom' => 'yes' }, mandatory: true)
@@ -287,12 +305,7 @@ RSpec.describe 'LLM fleet message envelopes' do
     it 'returns a transport-style failure result for transient reply publish errors' do
       default_exchange = instance_double(Bunny::Exchange, name: 'default')
       channel = instance_double(Bunny::Channel, default_exchange: default_exchange)
-      message = described_class.new(
-        request_id: 'req-1',
-        correlation_id: 'corr-1',
-        reply_to: 'llm.fleet.reply.node',
-        content: 'hello'
-      )
+      message = described_class.new(**valid_response_options)
 
       allow(default_exchange).to receive(:publish).and_raise(IOError, 'socket closed')
       allow(message).to receive(:channel).and_return(channel)
@@ -310,27 +323,20 @@ RSpec.describe 'LLM fleet message envelopes' do
   end
 
   describe Legion::Extensions::Llm::Transport::Messages::FleetError do
-    it 'builds a protocol v2 correlated error envelope' do
+    it 'builds a protocol v3 correlated error envelope (E6)' do
       message = described_class.new(
-        request_id: 'req-1',
-        correlation_id: 'corr-1',
-        idempotency_key: 'idem-1',
-        operation: :chat,
-        reply_to: 'llm.fleet.reply.node',
-        provider: :vllm,
-        provider_instance: :apollo,
-        model: 'qwen',
+        **valid_response_options.slice(:protocol_version, :request_id, :correlation_id, :idempotency_key, :operation,
+                                       :provider, :provider_instance, :model, :reply_to, :message_context,
+                                       :trace_context, :execution_contract, :offering_id),
         code: 'provider_failed',
         message: 'provider failed',
-        retryable: true,
-        message_context: { conversation_id: 'conv-1' },
-        trace_context: { trace_id: 'trace-1' }
+        retryable: true
       )
 
       expect(message.type).to eq(protocol::ERROR_TYPE)
       expect(message.routing_key).to eq('llm.fleet.reply.node')
       expect(message.message).to include(
-        protocol_version: 2,
+        protocol_version: 3,
         request_id: 'req-1',
         correlation_id: 'corr-1',
         idempotency_key: 'idem-1',
@@ -342,35 +348,28 @@ RSpec.describe 'LLM fleet message envelopes' do
         code: 'provider_failed',
         message: 'provider failed',
         retryable: true,
-        message_context: { conversation_id: 'conv-1' },
-        trace_context: { trace_id: 'trace-1' }
+        execution_contract: protocol::EXACT_EXECUTION_CONTRACT,
+        offering_id: 'local:vllm:h200:inference:gemma4'
       )
-      expect(message.message).not_to include(:schema_version)
+      expect(message.message).not_to include(:schema_version, :instance)
     end
 
-    it 'rejects error protocol versions other than v2' do
+    it 'rejects error protocol versions other than v3 and missing versions' do
+      base = valid_response_options.slice(:request_id, :correlation_id, :reply_to)
       expect do
-        described_class.new(
-          request_id: 'req-1',
-          correlation_id: 'corr-1',
-          reply_to: 'llm.fleet.reply.node',
-          code: 'provider_failed',
-          message: 'provider failed',
-          protocol_version: 1
-        )
-      end.to raise_error(ArgumentError, /protocol_version/)
+        described_class.new(**base, protocol_version: 2, code: 'provider_failed', message: 'provider failed')
+      end.to raise_error(ArgumentError, /protocol_version must be 3/)
+      expect do
+        described_class.new(**base, code: 'provider_failed', message: 'provider failed')
+      end.to raise_error(ArgumentError, /protocol_version is required/)
     end
 
     it 'publishes errors through the AMQP default exchange without confirms or mandatory routing' do
       default_exchange = instance_double(Bunny::Exchange, publish: true)
       channel = instance_double(Bunny::Channel, default_exchange: default_exchange)
-      message = described_class.new(
-        request_id: 'req-1',
-        correlation_id: 'corr-1',
-        reply_to: 'llm.fleet.reply.node',
-        code: 'provider_failed',
-        message: 'provider failed'
-      )
+      message = described_class.new(**valid_response_options.slice(:protocol_version, :request_id, :correlation_id,
+                                                                   :reply_to),
+                                    code: 'provider_failed', message: 'provider failed')
 
       allow(message).to receive(:channel).and_return(channel)
       message.publish
@@ -390,13 +389,9 @@ RSpec.describe 'LLM fleet message envelopes' do
       channel = instance_double(channel_class, default_exchange: nil, on_return: nil)
       default_exchange = instance_double(Bunny::Exchange, publish: true, name: 'default', channel: channel)
       allow(channel).to receive(:default_exchange).and_return(default_exchange)
-      message = described_class.new(
-        request_id: 'req-1',
-        correlation_id: 'corr-1',
-        reply_to: 'llm.fleet.reply.node',
-        code: 'provider_failed',
-        message: 'provider failed'
-      )
+      message = described_class.new(**valid_response_options.slice(:protocol_version, :request_id, :correlation_id,
+                                                                   :reply_to),
+                                    code: 'provider_failed', message: 'provider failed')
 
       allow(message).to receive(:channel).and_return(channel)
       result = message.publish(return_result: true, headers: { 'x-custom' => 'yes' }, mandatory: true)
@@ -413,4 +408,3 @@ RSpec.describe 'LLM fleet message envelopes' do
     end
   end
 end
-# rubocop:enable RSpec/DescribeClass

data/spec/legion/extensions/llm/gemspec_spec.rb

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-# rubocop:disable RSpec/DescribeClass
+# rubocop:disable-next RSpec/DescribeClass
 RSpec.describe 'lex-llm.gemspec' do
   subject(:gemspec) { Gem::Specification.load(File.expand_path('../../../../lex-llm.gemspec', __dir__)) }
 
@@ -22,4 +22,3 @@ RSpec.describe 'lex-llm.gemspec' do
     expect(gemspec.name).to eq('lex-llm')
   end
 end
-# rubocop:enable RSpec/DescribeClass