lex-llm 0.6.16 → 0.7.2

data/spec/legion/extensions/llm/conformance/fixtures/ssot_identity_vectors.json

@@ -0,0 +1,84 @@
+{
+  "description": "Binding SSOT v3 identity input/byte/digest fixtures. Recompute every field and digest; do not merely check a prefix. No Ruby object hash, hash-iteration order, or delimiter splitting is used anywhere.",
+  "algorithm": {
+    "frame": "binary bytes: decimal(UTF-8 byte length) + ASCII 0x3a colon + exact UTF-8 bytes",
+    "offering_id": "off:v1: + lowercase_hex(SHA256(frame(provider_family) + frame(instance_id) + frame(provider_native_key)))",
+    "lane_id": "lane:v1: + lowercase_hex(SHA256(ASCII(\"lane-v1\\u0000\") + frame(provider_family) + frame(instance_id) + frame(operation) + frame(model) + frame(offering_id)))",
+    "lane_domain_prefix_hex": "6c616e652d763100",
+    "notes": "Tier is never an identity input. provider_native_key, model, and offering_id preserve declared case."
+  },
+  "vectors": [
+    {
+      "provider_family": "vllm",
+      "instance_id": "h200",
+      "provider_native_key": "gemma4",
+      "model": "gemma4",
+      "operation": "chat",
+      "framed_hex": {
+        "provider_family": "343a766c6c6d",
+        "instance_id": "343a68323030",
+        "provider_native_key": "363a67656d6d6134",
+        "operation": "343a63686174",
+        "model": "363a67656d6d6134",
+        "offering_id": "37313a6f66663a76313a63393636373732643766386634323863323461373762653936663934653131316261313035326266303933303938663034313362353632633130353964636431"
+      },
+      "offering_hash_input_hex": "343a766c6c6d343a68323030363a67656d6d6134",
+      "expected_offering_id": "off:v1:c966772d7f8f428c24a77be96f94e111ba1052bf093098f0413b562c1059dcd1",
+      "lane_hash_input_hex": "6c616e652d763100343a766c6c6d343a68323030343a63686174363a67656d6d613437313a6f66663a76313a63393636373732643766386634323863323461373762653936663934653131316261313035326266303933303938663034313362353632633130353964636431",
+      "expected_lane_id": "lane:v1:430444bb58975ab56329c7c3a6c483a1b9cb49d1c089a56f3c93c6aa27d5f9b3"
+    },
+    {
+      "provider_family": "vllm",
+      "instance_id": "helios1",
+      "provider_native_key": "gemma4",
+      "model": "gemma4",
+      "operation": "chat",
+      "framed_hex": {
+        "provider_family": "343a766c6c6d",
+        "instance_id": "373a68656c696f7331",
+        "provider_native_key": "363a67656d6d6134",
+        "operation": "343a63686174",
+        "model": "363a67656d6d6134",
+        "offering_id": "37313a6f66663a76313a66336333316366313830313739363436343163386166656463656261316136366135326661626630313463666632623365316438383165333639376339656334"
+      },
+      "offering_hash_input_hex": "343a766c6c6d373a68656c696f7331363a67656d6d6134",
+      "expected_offering_id": "off:v1:f3c31cf18017964641c8afedceba1a66a52fabf014cff2b3e1d881e3697c9ec4",
+      "lane_hash_input_hex": "6c616e652d763100343a766c6c6d373a68656c696f7331343a63686174363a67656d6d613437313a6f66663a76313a66336333316366313830313739363436343163386166656463656261316136366135326661626630313463666632623365316438383165333639376339656334",
+      "expected_lane_id": "lane:v1:e4a99f7884ea1e9c36b0a0e62da5038832857f0e4b69234133faa81b0e30e880"
+    },
+    {
+      "provider_family": "azure_foundry",
+      "instance_id": "prod:eastus",
+      "provider_native_key": "deploy:gpt-4o",
+      "model": "gpt-4o",
+      "operation": "chat",
+      "framed_hex": {
+        "provider_family": "31333a617a7572655f666f756e647279",
+        "instance_id": "31313a70726f643a656173747573",
+        "provider_native_key": "31333a6465706c6f793a6770742d346f",
+        "operation": "343a63686174",
+        "model": "363a6770742d346f",
+        "offering_id": "37313a6f66663a76313a37646431346639386164346266656335316666623136396561323064633137616564316562653033613363396664666365383966383638343534633035646137"
+      },
+      "offering_hash_input_hex": "31333a617a7572655f666f756e64727931313a70726f643a65617374757331333a6465706c6f793a6770742d346f",
+      "expected_offering_id": "off:v1:7dd14f98ad4bfec51ffb169ea20dc17aed1ebe03a3c9fdfce89f868454c05da7",
+      "lane_hash_input_hex": "6c616e652d76310031333a617a7572655f666f756e64727931313a70726f643a656173747573343a63686174363a6770742d346f37313a6f66663a76313a37646431346639386164346266656335316666623136396561323064633137616564316562653033613363396664666365383966383638343534633035646137",
+      "expected_lane_id": "lane:v1:2334bc87506ae6312a4f64b53798d723d07279294ee6a3181e23db298cf910aa"
+    }
+  ],
+  "tier_invariance": {
+    "note": "The vllm+h200+gemma4+chat vector reproduces identical offering_id/lane_id under every tier; tier is not framed.",
+    "base_vector_index": 0,
+    "tiers": [
+      "local",
+      "frontier"
+    ]
+  },
+  "independence": {
+    "note": "vectors[0] and vectors[1] share provider_family+model but differ by instance_id, proving vllm+h200+gemma4 and vllm+helios1+gemma4 are independent identities.",
+    "vector_indexes": [
+      0,
+      1
+    ]
+  }
+}

data/spec/legion/extensions/llm/conformance/ssot_provider_conformance_spec.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require_relative 'ssot_provider_examples'
+require_relative '../../../../support/fake_ssot_harness'
+
+# Self-test: the Phase 1 fake harness must satisfy the shared provider examples,
+# proving the examples are correct and consumable by every provider PR.
+RSpec.describe SpecSupport::FakeSsotHarness do
+  let(:ssot_harness) { described_class.new }
+
+  it_behaves_like 'an SSOT v3 provider adapter'
+end

data/spec/legion/extensions/llm/conformance/ssot_provider_examples.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/inventory/publisher'
+require 'legion/extensions/llm/inventory/probe_coordinator'
+require 'legion/extensions/llm/fleet/worker_execution'
+require 'legion/extensions/llm/fleet/protocol'
+
+# Shared conformance examples required unchanged by every SSOT v3 provider PR.
+# The including provider spec supplies one `let(:ssot_harness)` implementing the
+# harness interface documented in phase-1-lex-llm-additive.md Task 12. These
+# examples drive only the public Publisher/Registry API and never call a provider
+# actor implementation directly.
+RSpec.shared_examples 'an SSOT v3 provider adapter' do
+  harness_methods = %i[
+    provider_family instance_configs instance_id build_callable build_offering_drafts safe_readiness
+    inference_call_count normalize_dispatch_error instance_unavailable_error overloaded_error model_not_ready_error
+  ]
+
+  let(:registry) { Legion::Extensions::Llm::Inventory::Registry }
+  let(:configs) { ssot_harness.instance_configs }
+
+  before { registry.reset! }
+
+  def build_key(config)
+    Legion::Extensions::Llm::Inventory::Identity::InstanceKey.new(
+      provider_family: ssot_harness.provider_family, instance_id: ssot_harness.instance_id(instance_config: config)
+    )
+  end
+
+  def publisher_for
+    Legion::Extensions::Llm::Inventory::Publisher.new(provider_family: ssot_harness.provider_family)
+  end
+
+  def coordinator_for(key)
+    Legion::Extensions::Llm::Inventory::ProbeCoordinator.new(instance_key: key, enqueue: ->(**) { true })
+  end
+
+  # Claims and (when readiness succeeds) activates one instance through the public
+  # Publisher API. Returns the context needed for later assertions.
+  def bring_up(config, tier: :local)
+    publisher = publisher_for
+    key = build_key(config)
+    callable = ssot_harness.build_callable(instance_config: config)
+    token = publisher.claim_instance(instance_id: key.instance_id, callable: callable, probe_request_handle: coordinator_for(key))
+    probe = publisher.readiness_probe_started(instance_id: key.instance_id, publisher_token: token)
+    readiness = ssot_harness.safe_readiness(instance_config: config, callable: callable)
+    drafts = ssot_harness.build_offering_drafts(instance_config: config, callable: callable, tier: tier)
+    if readiness.ready?
+      publisher.activate_instance_snapshot(instance_id: key.instance_id, publisher_token: token, offerings: drafts, sequence: 0, probe_token: probe)
+    else
+      publisher.readiness_failed(instance_id: key.instance_id, probe_token: probe, reason: readiness.reason)
+    end
+    { publisher: publisher, key: key, callable: callable, token: token, drafts: drafts }
+  end
+
+  it 'implements the full harness interface' do
+    harness_methods.each do |method_name|
+      expect(ssot_harness).to respond_to(method_name), "ssot_harness must implement ##{method_name}"
+    end
+  end
+
+  it 'supplies two independent instances with distinct ids and distinct callables' do
+    expect(configs.size).to eq(2)
+    ids = configs.map { |config| ssot_harness.instance_id(instance_config: config) }
+    expect(ids.uniq.size).to eq(2)
+    callables = configs.map { |config| ssot_harness.build_callable(instance_config: config) }
+    expect(callables.first).not_to equal(callables.last)
+    expect(ssot_harness.safe_readiness(instance_config: configs.first, callable: callables.first))
+      .to be_a(Legion::Extensions::Llm::Inventory::ReadinessResult)
+  end
+
+  it 'publishes distinct identities and independently available lanes for the same model on two instances' do
+    a = bring_up(configs[0])
+    b = bring_up(configs[1])
+    snapshot = registry.snapshot
+    expect(snapshot.instance(instance_key: a[:key]).availability.state).to eq(:available)
+    expect(snapshot.instance(instance_key: b[:key]).availability.state).to eq(:available)
+    lane_a = snapshot.lanes_for(instance_key: a[:key]).first
+    lane_b = snapshot.lanes_for(instance_key: b[:key]).first
+    expect(lane_a.lane_id).not_to eq(lane_b.lane_id)
+    expect(lane_a.offering_id).not_to eq(lane_b.offering_id)
+  end
+
+  it 'exposes no selector-visible model or callable before startup readiness' do
+    publisher = publisher_for
+    key = build_key(configs[0])
+    publisher.claim_instance(instance_id: key.instance_id, callable: ssot_harness.build_callable(instance_config: configs[0]), probe_request_handle: coordinator_for(key))
+    expect(registry.snapshot.instance(instance_key: key)).to be_nil
+    expect(registry.snapshot.publication_status(instance_key: key).state).to eq(:initializing)
+  end
+
+  it 'leaves the instance initializing after an initial readiness failure' do
+    publisher = publisher_for
+    key = build_key(configs[0])
+    token = publisher.claim_instance(instance_id: key.instance_id, callable: ssot_harness.build_callable(instance_config: configs[0]), probe_request_handle: coordinator_for(key))
+    probe = publisher.readiness_probe_started(instance_id: key.instance_id, publisher_token: token)
+    publisher.readiness_failed(instance_id: key.instance_id, probe_token: probe, reason: 'probe failed')
+    expect(registry.snapshot.instance(instance_key: key)).to be_nil
+    expect(registry.snapshot.publication_status(instance_key: key).state).to eq(:initializing)
+  end
+
+  it 'performs no provider inference during readiness' do
+    context = bring_up(configs[0])
+    expect(ssot_harness.inference_call_count(callable: context[:callable])).to eq(0)
+  end
+
+  it 'supports complete refresh, complete empty, and failed-refresh retention' do
+    context = bring_up(configs[0])
+    context[:publisher].replace_instance_snapshot(instance_id: context[:key].instance_id, publisher_token: context[:token], offerings: context[:drafts], sequence: 1)
+    expect(registry.snapshot.offerings_for(instance_key: context[:key]).size).to eq(1)
+    context[:publisher].replace_instance_snapshot(instance_id: context[:key].instance_id, publisher_token: context[:token], offerings: [], sequence: 2)
+    expect(registry.snapshot.offerings_for(instance_key: context[:key])).to be_empty
+    expect do
+      context[:publisher].replace_instance_snapshot(instance_id: context[:key].instance_id, publisher_token: context[:token], offerings: [], sequence: 2)
+    end.to raise_error(Legion::Extensions::Llm::Inventory::Errors::StaleSequenceError)
+  end
+
+  it 'preserves offering and lane identity across a tier-only republication' do
+    context = bring_up(configs[0], tier: :local)
+    before_offering = registry.snapshot.offerings_for(instance_key: context[:key]).first.offering_id
+    before_lane = registry.snapshot.lanes_for(instance_key: context[:key]).first.lane_id
+    frontier_drafts = ssot_harness.build_offering_drafts(instance_config: configs[0], callable: context[:callable], tier: :frontier)
+    context[:publisher].replace_instance_snapshot(instance_id: context[:key].instance_id, publisher_token: context[:token], offerings: frontier_drafts, sequence: 1)
+    expect(registry.snapshot.offerings_for(instance_key: context[:key]).first.offering_id).to eq(before_offering)
+    expect(registry.snapshot.lanes_for(instance_key: context[:key]).first.lane_id).to eq(before_lane)
+  end
+
+  it 'refuses recovery from a stale probe started before the failure' do
+    context = bring_up(configs[0])
+    stale = context[:publisher].readiness_probe_started(instance_id: context[:key].instance_id, publisher_token: context[:token])
+    fresh = context[:publisher].readiness_probe_started(instance_id: context[:key].instance_id, publisher_token: context[:token])
+    context[:publisher].readiness_failed(instance_id: context[:key].instance_id, probe_token: fresh, reason: 'down')
+    result = context[:publisher].readiness_succeeded(instance_id: context[:key].instance_id, probe_token: stale)
+    expect(result.applied).to be(false)
+    expect(result.reason).to eq(:stale_probe)
+  end
+
+  it 'marks only one exact instance unavailable on a normalized instance_unavailable outcome' do
+    a = bring_up(configs[0])
+    b = bring_up(configs[1])
+    outcome = ssot_harness.normalize_dispatch_error(error: ssot_harness.instance_unavailable_error)
+    expect(outcome.kind).to eq(:instance_unavailable)
+    registry.dispatch_instance_unavailable(instance_key: a[:key], publisher_token_id: a[:token].publisher_token_id, reason: outcome.reason)
+    expect(registry.snapshot.instance(instance_key: a[:key]).availability.state).to eq(:unavailable)
+    expect(registry.snapshot.instance(instance_key: b[:key]).availability.state).to eq(:available)
+  end
+
+  it 'keeps overload and model-not-ready request-local regardless of 503/529 transport status' do
+    expect(ssot_harness.normalize_dispatch_error(error: ssot_harness.overloaded_error).kind).to eq(:overloaded)
+    expect(ssot_harness.normalize_dispatch_error(error: ssot_harness.model_not_ready_error).kind).to eq(:model_not_ready)
+    expect(ssot_harness.normalize_dispatch_error(error: ssot_harness.overloaded_error).kind).not_to eq(:instance_unavailable)
+  end
+
+  it 'executes an exact fleet request against only the captured callable' do
+    allow(Legion::Extensions::Llm::Fleet::WorkerExecution).to receive_messages(validate_identity!: true, validate_idempotency!: nil)
+    context = bring_up(configs[0])
+    offering = registry.snapshot.offerings_for(instance_key: context[:key]).first
+    envelope = {
+      execution_contract: Legion::Extensions::Llm::Fleet::Protocol::EXACT_EXECUTION_CONTRACT,
+      offering_id: offering.offering_id, provider: ssot_harness.provider_family.to_s,
+      provider_instance: context[:key].instance_id, model: offering.model, operation: 'chat', params: { messages: [] }
+    }
+    Legion::Extensions::Llm::Fleet::WorkerExecution.call(envelope: envelope, registry: registry)
+    expect(ssot_harness.inference_call_count(callable: context[:callable])).to eq(1)
+  end
+
+  it 'rejects provider/model defaults and a nil instance' do
+    identity = Legion::Extensions::Llm::Inventory::Identity
+    expect { identity::InstanceKey.new(provider_family: ssot_harness.provider_family, instance_id: 'default') }
+      .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+    expect { identity::InstanceKey.new(provider_family: ssot_harness.provider_family, instance_id: nil) }
+      .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+  end
+
+  it 'exposes snapshot each_instance and each_publication_status as ordered blockless enumerators' do
+    bring_up(configs[0])
+    bring_up(configs[1])
+    snapshot = registry.snapshot
+    expect(snapshot.each_instance).to be_a(Enumerator)
+    expect(snapshot.each_publication_status).to be_a(Enumerator)
+    ordered_ids = snapshot.each_instance.map { |record| [record.instance_key.provider_family.to_s, record.instance_key.instance_id] }
+    expect(ordered_ids).to eq(ordered_ids.sort)
+    expect(snapshot.each_publication_status.map(&:state)).to all(eq(:complete))
+  end
+
+  it 'normalizes a dispatch error into a ProviderOutcome on the captured callable itself' do
+    callable = ssot_harness.build_callable(instance_config: configs[0])
+    expect(callable).to respond_to(:normalize_dispatch_error)
+    unavailable = callable.normalize_dispatch_error(error: Legion::Extensions::Llm::ServiceUnavailableError.new('503'))
+    expect(unavailable).to be_a(Legion::Extensions::Llm::Routing::ProviderOutcome)
+    expect(unavailable.kind).to eq(:provider_error)
+    expect(unavailable.kind).not_to eq(:instance_unavailable)
+    overloaded = callable.normalize_dispatch_error(error: Legion::Extensions::Llm::OverloadedError.new('529'))
+    expect(overloaded.kind).to eq(:overloaded)
+  end
+end

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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/fleet/worker_execution'
+require 'legion/extensions/llm/fleet/token_validator'
+require 'legion/extensions/llm/fleet/protocol'
+require_relative '../../../../support/ssot_registry_helpers'
+
+module Legion
+  module Extensions
+    module Llm
+      module Fleet
+        # Test-only anchor aligning this spec's path with its describe target.
+        module ExactOffering; end
+      end
+    end
+  end
+end
+
+RSpec.describe Legion::Extensions::Llm::Fleet::ExactOffering do
+  include SsotRegistryHelpers
+
+  inventory = Legion::Extensions::Llm::Inventory
+  errors = inventory::Errors
+  worker = Legion::Extensions::Llm::Fleet::WorkerExecution
+  protocol = Legion::Extensions::Llm::Fleet::Protocol
+  token_validator = Legion::Extensions::Llm::Fleet::TokenValidator
+
+  let(:recording_callable) do
+    Class.new do
+      attr_reader :calls
+
+      def initialize
+        @calls = []
+      end
+
+      def disconnect; end
+
+      def chat(messages:, model:, **rest)
+        @calls << { op: :chat, messages: messages, model: model, rest: rest }
+        { content: 'exact-ok' }
+      end
+
+      def embed(text:, model:, **rest)
+        @calls << { op: :embed, text: text, model: model, rest: rest }
+        { content: 'embed-ok' }
+      end
+    end.new
+  end
+
+  let(:key) { instance_key(family: 'vllm', instance: 'h200') }
+
+  before do
+    inventory::Registry.reset!
+    claim_and_activate(key: key, callable: recording_callable, coordinator: probe_coordinator(key))
+    allow(worker).to receive_messages(validate_identity!: true, validate_idempotency!: nil)
+  end
+
+  def offering_id
+    Legion::Extensions::Llm::Inventory::Identity.offering_id(instance_key: key, provider_native_key: 'gemma4')
+  end
+
+  def exact_envelope(**overrides)
+    {
+      execution_contract: Legion::Extensions::Llm::Fleet::Protocol::EXACT_EXECUTION_CONTRACT, offering_id: offering_id,
+      provider: 'vllm', provider_instance: 'h200', model: 'gemma4', operation: 'chat',
+      params: { messages: [] }
+    }.merge(overrides)
+  end
+
+  def handle_reference_count
+    Legion::Extensions::Llm::Inventory::Registry.snapshot.instance(instance_key: key).callable_handle.reference_count
+  end
+
+  describe 'exact dispatch' do
+    it 'invokes only the captured callable and releases the lease' do
+      worker.call(envelope: exact_envelope, registry: inventory::Registry)
+      expect(recording_callable.calls.map { |c| c[:op] }).to eq([:chat])
+      expect(handle_reference_count).to eq(0)
+    end
+
+    it 'requires exactly one of registry or provider' do
+      expect { worker.call(envelope: exact_envelope, registry: inventory::Registry, provider: Object.new) }
+        .to raise_error(worker::PolicyError)
+      expect { worker.call(envelope: exact_envelope) }.to raise_error(worker::PolicyError)
+    end
+
+    it 'releases the lease even when the callable raises' do
+      allow(recording_callable).to receive(:chat).and_raise(StandardError, 'boom')
+      expect { worker.call(envelope: exact_envelope, registry: inventory::Registry) }.to raise_error(StandardError)
+      expect(handle_reference_count).to eq(0)
+    end
+
+    it 'rejects a mismatched offering_id, model, operation, and absent instance before invocation' do
+      expect { worker.call(envelope: exact_envelope(offering_id: "off:v1:#{'0' * 64}"), registry: inventory::Registry) }
+        .to raise_error(errors::ExactOfferingMismatchError)
+      expect { worker.call(envelope: exact_envelope(model: 'other'), registry: inventory::Registry) }
+        .to raise_error(errors::ExactOfferingMismatchError)
+      expect { worker.call(envelope: exact_envelope(operation: 'embed'), registry: inventory::Registry) }
+        .to raise_error(errors::ExactOfferingMismatchError)
+      expect { worker.call(envelope: exact_envelope(provider_instance: 'absent'), registry: inventory::Registry) }
+        .to raise_error(errors::ExactOfferingMismatchError)
+      expect(recording_callable.calls).to be_empty
+    end
+
+    it 'rejects duplicate String/Symbol param spellings' do
+      expect { worker.call(envelope: exact_envelope(params: { 'messages' => [], :messages => [] }), registry: inventory::Registry) }
+        .to raise_error(errors::ExactOfferingMismatchError)
+    end
+
+    it 'rejects a params-supplied model (envelope model is the only model)' do
+      expect { worker.call(envelope: exact_envelope(params: { messages: [], model: 'x' }), registry: inventory::Registry) }
+        .to raise_error(errors::ExactOfferingMismatchError)
+    end
+
+    it 'rejects a missing required operation param' do
+      expect { worker.call(envelope: exact_envelope(params: {}), registry: inventory::Registry) }
+        .to raise_error(errors::ExactOfferingMismatchError)
+    end
+
+    it 'passes an explicit empty messages array and forwards unknown kwargs' do
+      worker.call(envelope: exact_envelope(params: { messages: [], temperature: 0.2 }), registry: inventory::Registry)
+      call = recording_callable.calls.first
+      expect(call[:messages]).to eq([])
+      expect(call[:rest]).to eq(temperature: 0.2)
+    end
+  end
+
+  describe 'registry-backed legacy v2 resolution' do
+    def activate_two_offerings
+      registry = Legion::Extensions::Llm::Inventory::Registry
+      registry.reset!
+      token = registry.claim_instance(instance_key: key, callable: recording_callable, probe_request_handle: probe_coordinator(key))
+      probe = registry.readiness_probe_started(instance_key: key, publisher_token: token)
+      two = drafts(native: 'a', model: 'gemma4') + drafts(native: 'b', model: 'gemma4')
+      registry.activate_instance_snapshot(publisher_token: token, instance_key: key, offerings: two, sequence: 0, probe_token: probe)
+    end
+
+    it 'refuses zero matches' do
+      envelope = { provider: 'vllm', provider_instance: 'h200', model: 'nope', operation: 'chat', params: { messages: [] } }
+      expect { worker.call(envelope: envelope, registry: inventory::Registry) }.to raise_error(errors::ExactOfferingMismatchError)
+    end
+
+    it 'refuses multiple matches' do
+      activate_two_offerings
+      envelope = { provider: 'vllm', provider_instance: 'h200', model: 'gemma4', operation: 'chat', params: { messages: [] } }
+      expect { worker.call(envelope: envelope, registry: inventory::Registry) }.to raise_error(errors::AmbiguousLegacyOfferingError)
+    end
+  end
+
+  describe 'legacy provider path still operates' do
+    it 'dispatches through the provider object without a registry' do
+      provider = recording_callable
+      envelope = { operation: 'chat', model: 'gemma4', params: { messages: [] } }
+      worker.call(envelope: envelope, provider: provider)
+      expect(recording_callable.calls.map { |c| c[:op] }).to eq([:chat])
+    end
+  end
+
+  describe 'TokenValidator exact signed claims' do
+    it 'requires both exact scalar claims to be signed and to match when the marker is present' do
+      envelope = { execution_contract: protocol::EXACT_EXECUTION_CONTRACT, offering_id: offering_id }
+      good = { execution_contract: protocol::EXACT_EXECUTION_CONTRACT, offering_id: offering_id }
+      expect { token_validator.validate_exact_execution_claims!(good, envelope) }.not_to raise_error
+
+      missing = { execution_contract: protocol::EXACT_EXECUTION_CONTRACT }
+      expect { token_validator.validate_exact_execution_claims!(missing, envelope) }
+        .to raise_error(Legion::Extensions::Llm::Fleet::TokenError)
+
+      mismatched = { execution_contract: protocol::EXACT_EXECUTION_CONTRACT, offering_id: "off:v1:#{'0' * 64}" }
+      expect { token_validator.validate_exact_execution_claims!(mismatched, envelope) }
+        .to raise_error(Legion::Extensions::Llm::Fleet::TokenError)
+    end
+
+    it 'is a no-op for a legacy v2 envelope without the marker' do
+      expect { token_validator.validate_exact_execution_claims!({}, { operation: 'chat' }) }.not_to raise_error
+    end
+  end
+end

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

@@ -117,4 +117,30 @@ RSpec.describe Legion::Extensions::Llm::Fleet::ProviderResponder do
       described_class.transport_message_class(:FleetResponse)
     end.to raise_error(described_class::ConfigurationError, /fleet responder transport unavailable/)
   end
+
+  describe 'execution_contract marker validation' do
+    it 'accepts a legacy v2 envelope with no marker' do
+      envelope = described_class.parse_payload(payload)
+      expect { described_class.check_envelope!(envelope, provider_family: :ollama) }.not_to raise_error
+    end
+
+    it 'rejects an unknown nonempty marker' do
+      envelope = described_class.parse_payload(payload.merge(execution_contract: 'made_up'))
+      expect { described_class.check_envelope!(envelope, provider_family: :ollama) }
+        .to raise_error(ArgumentError, /unknown execution_contract/)
+    end
+
+    it 'requires offering_id for the exact marker' do
+      envelope = described_class.parse_payload(payload.merge(execution_contract: 'exact_offering_v1'))
+      expect { described_class.check_envelope!(envelope, provider_family: :ollama) }
+        .to raise_error(ArgumentError, /offering_id is required/)
+    end
+
+    it 'accepts a complete exact envelope' do
+      exact = payload.merge(execution_contract: 'exact_offering_v1', offering_id: 'off:v1:abc')
+      envelope = described_class.parse_payload(exact)
+      expect { described_class.check_envelope!(envelope, provider_family: :ollama) }.not_to raise_error
+      expect(described_class.exact?(envelope)).to be(true)
+    end
+  end
 end

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

@@ -189,6 +189,20 @@ RSpec.describe 'LLM fleet message envelopes' do
       expect(message.message).not_to include(:schema_version)
     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)
+    end
+
     it 'rejects response protocol versions other than v2' do
       expect do
         described_class.new(

data/spec/legion/extensions/llm/inventory/boot_spec.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # Test-only namespace anchor so this boot spec's file path aligns with its
+        # describe target under RSpec/SpecFilePathFormat. It adds no runtime
+        # behavior and exists only in the test load path.
+        module Boot; end
+      end
+    end
+  end
+end
+
+# Proves the SSOT v3 contract is wired by `require "legion/extensions/llm"`
+# alone, with no legion-llm, LegionIO, transport, database, or timer dependency.
+RSpec.describe Legion::Extensions::Llm::Inventory::Boot do
+  inventory = Legion::Extensions::Llm::Inventory
+
+  def build_callable
+    Class.new do
+      def disconnect; end
+    end.new
+  end
+
+  def probe_handle(key)
+    Legion::Extensions::Llm::Inventory::ProbeCoordinator.new(instance_key: key, enqueue: ->(**) { true })
+  end
+
+  def full_lifecycle(key)
+    registry = Legion::Extensions::Llm::Inventory::Registry
+    token = registry.claim_instance(instance_key: key, callable: build_callable, probe_request_handle: probe_handle(key))
+    probe = registry.readiness_probe_started(instance_key: key, publisher_token: token)
+    registry.activate_instance_snapshot(publisher_token: token, instance_key: key, offerings: [], sequence: 0, probe_token: probe)
+  end
+
+  before { inventory::Registry.reset! }
+
+  it 'loads without Legion::LLM or LegionIO present' do
+    expect(defined?(Legion::LLM)).to be_nil
+    expect(defined?(LegionIO)).to be_nil
+  end
+
+  it 'exposes every require-order constant' do
+    %i[
+      Errors ImmutableValue Identity Evidence CallableHandle DispatchLease ProbeToken ProbeRequest
+      ProbeCoordinator PublisherToken OfferingDraft OfferingRecord LaneRecord AvailabilityFact
+      ReadinessResult InstanceRecord PublicationStatus MutationResult Snapshot Registry Publisher
+    ].each { |const| expect(inventory.const_defined?(const)).to be(true), "missing Inventory::#{const}" }
+    %i[AttemptTargetKey QuotaDomainKey Exclusion Selection Rejection BodyModelHintDecision ProviderOutcome].each do |const|
+      expect(Legion::Extensions::Llm::Routing.const_defined?(const)).to be(true), "missing Routing::#{const}"
+    end
+  end
+
+  it 'runs claim -> probe -> activate -> snapshot after only requiring the extension' do
+    key = inventory::Identity::InstanceKey.new(provider_family: 'vllm', instance_id: 'h200')
+    result = full_lifecycle(key)
+    expect(result.applied).to be(true)
+    expect(inventory::Registry.snapshot.instance(instance_key: key).availability.state).to eq(:available)
+  end
+
+  it 'creates no new thread during boot or a mutation' do
+    baseline = Thread.list.size
+    key = inventory::Identity::InstanceKey.new(provider_family: 'vllm', instance_id: 'thread-check')
+    full_lifecycle(key)
+    expect(Thread.list.size).to eq(baseline)
+  end
+
+  it 'retains legacy Types aliases and adds no new SSOT alias' do
+    expect(Legion::Extensions::Llm::Types.const_defined?(:ModelOffering, false)).to be(true)
+    expect(Legion::Extensions::Llm::Types.const_defined?(:InstanceKey, false)).to be(false)
+  end
+
+  it 'preserves the optional transport message registration (autoload or loaded)' do
+    expect(Legion::Extensions::Llm::Transport::Messages.const_defined?(:FleetResponse, false)).to be(true)
+  end
+end