lex-llm 0.6.16 → 0.7.2

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/probe_coordinator'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::ProbeCoordinator do
+  inventory = Legion::Extensions::Llm::Inventory
+  errors = inventory::Errors
+
+  let(:instance_key) { inventory::Identity::InstanceKey.new(provider_family: 'vllm', instance_id: 'h200') }
+  let(:enqueued) { [] }
+  let(:enqueue_result) { [true] }
+  let(:enqueue) do
+    lambda { |request:|
+      enqueued << request
+      enqueue_result.first
+    }
+  end
+  let(:coordinator) { described_class.new(instance_key: instance_key, enqueue: enqueue) }
+
+  def enqueue_request(revision)
+    coordinator.enqueue_probe_request(
+      instance_key: instance_key, publisher_token_id: 'ptok:v1:x', unavailable_revision: revision, reason: 'dispatch unavailable'
+    )
+  end
+
+  it 'does not invoke enqueue at construction (enqueue-only)' do
+    coordinator
+    expect(enqueued).to be_empty
+  end
+
+  it 'enqueues a ProbeRequest built from the reported parameters' do
+    enqueue_request(1)
+    expect(enqueued.size).to eq(1)
+    expect(enqueued.first).to be_a(inventory::ProbeRequest)
+    expect(enqueued.first.unavailable_revision).to eq(1)
+  end
+
+  it 'rejects a request for a different instance' do
+    other = inventory::Identity::InstanceKey.new(provider_family: 'vllm', instance_id: 'helios1')
+    expect do
+      coordinator.enqueue_probe_request(instance_key: other, publisher_token_id: 'ptok:v1:x', unavailable_revision: 1, reason: 'x')
+    end.to raise_error(errors::ValidationError)
+  end
+
+  it 'coalesces duplicate-revision requests to a single enqueue' do
+    enqueue_request(5)
+    enqueue_request(5)
+    expect(enqueued.size).to eq(1)
+    expect(coordinator.pending?(unavailable_revision: 5)).to be(true)
+  end
+
+  it 'retains only the greatest pending revision without re-enqueuing' do
+    enqueue_request(5)
+    enqueue_request(7)
+    expect(enqueued.size).to eq(1)
+    expect(coordinator.pending?(unavailable_revision: 7)).to be(true)
+    expect(coordinator.pending?(unavailable_revision: 5)).to be(false)
+  end
+
+  it 'retains pending and returns false when enqueue fails, without inline readiness' do
+    enqueue_result[0] = false
+    expect(enqueue_request(3)).to be(false)
+    expect(coordinator.pending?(unavailable_revision: 3)).to be(true)
+  end
+
+  describe 'single flight and post-finish re-enqueue' do
+    it 'admits one flight, holds newer work, and re-enqueues the greatest pending on finish' do
+      enqueue_request(5)
+      first = enqueued.last
+      expect(coordinator.begin_probe(request: first)).to be(true)
+      expect(coordinator.in_flight?).to be(true)
+
+      # A newer revision arrives during the flight: retained, not enqueued.
+      enqueue_request(7)
+      expect(enqueued.size).to eq(1)
+
+      coordinator.finish_probe(request: first)
+      expect(coordinator.in_flight?).to be(false)
+      expect(enqueued.size).to eq(2)
+      expect(enqueued.last.unavailable_revision).to eq(7)
+    end
+
+    it 'rejects a second begin while a flight is active' do
+      enqueue_request(5)
+      expect(coordinator.begin_probe(request: enqueued.last)).to be(true)
+      expect(coordinator.begin_probe(request: nil)).to be(false)
+    end
+
+    it 'supports the cadence (nil) begin/finish form and rejects a mismatched finish form' do
+      mismatched = inventory::ProbeRequest.new(
+        instance_key: instance_key, publisher_token_id: 'ptok:v1:x', unavailable_revision: 1, reason: 'x'
+      )
+      expect(coordinator.begin_probe(request: nil)).to be(true)
+      expect { coordinator.finish_probe(request: mismatched) }.to raise_error(errors::InvalidTransitionError)
+      expect { coordinator.finish_probe(request: nil) }.not_to raise_error
+      expect(coordinator.in_flight?).to be(false)
+    end
+
+    it 'only admits a begin for the exact greatest pending request' do
+      enqueue_request(5)
+      stale = enqueued.last
+      enqueue_request(9) # replaces pending; stale is no longer greatest
+      expect(coordinator.begin_probe(request: stale)).to be(false)
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/probe_token'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::ProbeToken do
+  inventory = Legion::Extensions::Llm::Inventory
+  errors = inventory::Errors
+
+  let(:instance_key) { inventory::Identity::InstanceKey.new(provider_family: 'vllm', instance_id: 'h200') }
+
+  it 'issues a frozen, immutable probe token' do
+    token = described_class.issue(
+      instance_key: instance_key, publisher_token_id: 'ptok:v1:abc', started_availability_revision: 0, started_at: Time.now
+    )
+    expect(token.token_id).to start_with('probe:v1:')
+    expect(token).to be_frozen
+  end
+
+  it 'validates its fields' do
+    expect do
+      described_class.issue(instance_key: instance_key, publisher_token_id: 'nope', started_availability_revision: 0, started_at: Time.now)
+    end.to raise_error(errors::ValidationError)
+    expect do
+      described_class.issue(instance_key: instance_key, publisher_token_id: 'ptok:v1:x', started_availability_revision: -1, started_at: Time.now)
+    end.to raise_error(errors::ValidationError)
+  end
+
+  describe Legion::Extensions::Llm::Inventory::PublisherToken do
+    let(:token) { described_class.issue(instance_key: instance_key) }
+
+    describe '.issue' do
+      it 'derives pub:v1: and ptok:v1: correlation IDs and is frozen' do
+        expect(token.publisher_id).to start_with('pub:v1:')
+        expect(token.publisher_token_id).to start_with('ptok:v1:')
+        expect(token).to be_frozen
+      end
+
+      it 'derives publisher_token_id from the secret domain-separated SHA-256' do
+        other = described_class.issue(instance_key: instance_key)
+        expect(token.publisher_token_id).not_to eq(other.publisher_token_id)
+      end
+    end
+
+    describe 'secret redaction' do
+      it 'never exposes the secret through a public reader' do
+        expect(token).not_to respond_to(:secret)
+      end
+
+      it 'redacts the secret in inspect/to_s' do
+        expect(token.inspect).to include('[REDACTED]')
+        expect(token.inspect).not_to match(/secret=[0-9a-f]{8}/)
+        expect(token.to_s).to include('[REDACTED]')
+      end
+    end
+
+    describe '#authenticates?' do
+      it 'rejects a token with a different secret' do
+        other = described_class.issue(instance_key: instance_key)
+        expect(token.authenticates?(other)).to be(false)
+      end
+
+      it 'rejects a token for a different instance' do
+        other_key = inventory::Identity::InstanceKey.new(provider_family: 'vllm', instance_id: 'helios1')
+        other = described_class.issue(instance_key: other_key)
+        expect(token.authenticates?(other)).to be(false)
+      end
+
+      it 'rejects a non-PublisherToken' do
+        expect(token.authenticates?(Object.new)).to be(false)
+      end
+
+      it 'authenticates two tokens built from the same secret' do
+        secret = 'deadbeef' * 8
+        token_id = described_class.derive_token_id(secret)
+        a = described_class.new(instance_key: instance_key, secret: secret, publisher_id: 'pub:v1:x', publisher_token_id: token_id)
+        b = described_class.new(instance_key: instance_key, secret: secret, publisher_id: 'pub:v1:y', publisher_token_id: token_id)
+        expect(a.authenticates?(b)).to be(true)
+      end
+    end
+
+    describe 'validation' do
+      it 'rejects a non-InstanceKey and malformed ids' do
+        expect { described_class.new(instance_key: :vllm, secret: 'x', publisher_id: 'pub:v1:a', publisher_token_id: 'ptok:v1:a') }
+          .to raise_error(errors::ValidationError)
+        expect { described_class.new(instance_key: instance_key, secret: 'x', publisher_id: 'bad', publisher_token_id: 'ptok:v1:a') }
+          .to raise_error(errors::ValidationError)
+      end
+    end
+  end
+
+  describe Legion::Extensions::Llm::Inventory::ProbeRequest do
+    it 'requires a positive unavailable_revision and a ptok:v1: publisher token id' do
+      request = described_class.new(instance_key: instance_key, publisher_token_id: 'ptok:v1:x', unavailable_revision: 3, reason: 'dispatch reported unavailable')
+      expect(request.unavailable_revision).to eq(3)
+      expect { described_class.new(instance_key: instance_key, publisher_token_id: 'ptok:v1:x', unavailable_revision: 0, reason: 'x') }
+        .to raise_error(errors::ValidationError)
+      expect { described_class.new(instance_key: instance_key, publisher_token_id: 'nope', unavailable_revision: 1, reason: 'x') }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'sanitizes and bounds the reason' do
+      expect { described_class.new(instance_key: instance_key, publisher_token_id: 'ptok:v1:x', unavailable_revision: 1, reason: '  ') }
+        .to raise_error(errors::ValidationError)
+    end
+  end
+end

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/publisher'
+require_relative '../../../../support/ssot_registry_helpers'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Publisher do
+  include SsotRegistryHelpers
+
+  inventory = Legion::Extensions::Llm::Inventory
+
+  before { inventory::Registry.reset! }
+
+  # Records adapter invocations; returns a configurable outcome.
+  let(:adapter_calls) { [] }
+  let(:adapter_outcome) { [:applied] }
+  let(:adapter) do
+    calls = adapter_calls
+    outcome = adapter_outcome
+    Object.new.tap do |obj|
+      obj.define_singleton_method(:sync_snapshot) do |snapshot:, instance_key:, mutation_reason:|
+        calls << { snapshot: snapshot, instance_key: instance_key, mutation_reason: mutation_reason }
+        outcome.first
+      end
+    end
+  end
+
+  let(:publisher) { described_class.new(provider_family: :vllm, compatibility_adapter: adapter) }
+  let(:plain_publisher) { described_class.new(provider_family: :vllm) }
+
+  def full_activate(pub)
+    token = pub.claim_instance(instance_id: 'h200', callable: fake_callable, probe_request_handle: probe_coordinator(instance_key))
+    probe = pub.readiness_probe_started(instance_id: 'h200', publisher_token: token)
+    pub.activate_instance_snapshot(instance_id: 'h200', publisher_token: token, offerings: drafts, sequence: 0, probe_token: probe)
+    token
+  end
+
+  describe 'delegation' do
+    it 'claims, activates, and exposes the snapshot through the fixed provider family' do
+      full_activate(plain_publisher)
+      record = plain_publisher.snapshot.instance(instance_key: instance_key)
+      expect(record.availability.state).to eq(:available)
+      expect(record.instance_key.provider_family).to eq(:vllm)
+    end
+
+    it 'delegates removal with the publisher token' do
+      token = full_activate(plain_publisher)
+      result = plain_publisher.remove_instance(instance_id: 'h200', publisher_token: token)
+      expect(result.applied).to be(true)
+      expect(plain_publisher.snapshot.instance(instance_key: instance_key)).to be_nil
+    end
+  end
+
+  describe 'post-commit compatibility projection' do
+    it 'invokes the adapter after a successful claim and applied mutation with the committed snapshot' do
+      full_activate(publisher)
+      expect(adapter_calls.map { |c| c[:mutation_reason] }).to eq(%i[claimed activated])
+      # The adapter sees the already-committed snapshot on activation.
+      activation_call = adapter_calls.last
+      expect(activation_call[:snapshot].instance(instance_key: instance_key).availability.state).to eq(:available)
+      expect(activation_call[:instance_key]).to eq(instance_key)
+    end
+
+    it 'does not invoke the adapter for a non-applied (stale) mutation' do
+      token = full_activate(publisher)
+      adapter_calls.clear
+      # Supersede the publisher, then a stale replace returns applied: false.
+      publisher.claim_instance(instance_id: 'h200', callable: fake_callable, probe_request_handle: probe_coordinator(instance_key))
+      adapter_calls.clear
+      result = publisher.replace_instance_snapshot(instance_id: 'h200', publisher_token: token, offerings: drafts, sequence: 9)
+      expect(result.applied).to be(false)
+      expect(adapter_calls).to be_empty
+    end
+
+    it 'never changes the local result when the adapter returns :failed' do
+      adapter_outcome[0] = :failed
+      token = publisher.claim_instance(instance_id: 'h200', callable: fake_callable, probe_request_handle: probe_coordinator(instance_key))
+      expect(token).to be_a(inventory::PublisherToken)
+    end
+
+    it 'never changes the local result when the adapter raises' do
+      failing = Object.new.tap do |obj|
+        obj.define_singleton_method(:sync_snapshot) { |**| raise 'boom' }
+      end
+      pub = described_class.new(provider_family: :vllm, compatibility_adapter: failing)
+      expect { pub.claim_instance(instance_id: 'h200', callable: fake_callable, probe_request_handle: probe_coordinator(instance_key)) }
+        .not_to raise_error
+    end
+
+    it 'invokes the adapter again on the next applied cadence mutation' do
+      token = full_activate(publisher)
+      adapter_calls.clear
+      publisher.replace_instance_snapshot(instance_id: 'h200', publisher_token: token, offerings: drafts(native: 'gemma5', model: 'gemma5'), sequence: 1)
+      expect(adapter_calls.map { |c| c[:mutation_reason] }).to eq(%i[snapshot_replaced])
+    end
+  end
+
+  describe 'without a compatibility adapter' do
+    it 'performs no projection and returns the plain registry results' do
+      result = full_activate(plain_publisher)
+      expect(result).to be_a(inventory::PublisherToken)
+    end
+  end
+
+  describe 'secondary physical_id' do
+    it 'carries the physical id on the committed key while identity stays the config name' do
+      token = plain_publisher.claim_instance(
+        instance_id: 'h200', callable: fake_callable,
+        probe_request_handle: probe_coordinator(instance_key), physical_id: '10.0.0.1:8000/ak:abc123'
+      )
+      probe = plain_publisher.readiness_probe_started(instance_id: 'h200', publisher_token: token)
+      plain_publisher.activate_instance_snapshot(
+        instance_id: 'h200', publisher_token: token, offerings: drafts, sequence: 0, probe_token: probe
+      )
+
+      keyed_with_physical = inventory::Identity::InstanceKey.new(
+        provider_family: 'vllm', instance_id: 'h200', physical_id: '10.0.0.1:8000/ak:abc123'
+      )
+      record = plain_publisher.snapshot.instance(instance_key: keyed_with_physical)
+      expect(record).not_to be_nil
+      expect(record.instance_key.physical_id).to eq('10.0.0.1:8000/ak:abc123')
+
+      # Identity lookup without the physical id finds the same committed instance.
+      expect(plain_publisher.snapshot.instance(instance_key: instance_key)).to eq(record)
+    end
+
+    it 'replaces the same scope when the physical id changes for the same config name' do
+      old_token = plain_publisher.claim_instance(
+        instance_id: 'h200', callable: fake_callable,
+        probe_request_handle: probe_coordinator(instance_key), physical_id: '10.0.0.1:8000/ak:abc123'
+      )
+      new_token = plain_publisher.claim_instance(
+        instance_id: 'h200', callable: fake_callable,
+        probe_request_handle: probe_coordinator(instance_key), physical_id: '10.0.0.9:9000'
+      )
+
+      # The old publisher is superseded on the SAME scope (no parallel scope).
+      expect { plain_publisher.readiness_probe_started(instance_id: 'h200', publisher_token: old_token) }
+        .to raise_error(inventory::Errors::FencedPublisherError)
+      expect(plain_publisher.readiness_probe_started(instance_id: 'h200', publisher_token: new_token))
+        .to be_a(inventory::ProbeToken)
+    end
+  end
+end

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

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/records'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Records do
+  inventory = Legion::Extensions::Llm::Inventory
+  errors = inventory::Errors
+  identity = inventory::Identity
+  taxonomies = Legion::Extensions::Llm::Taxonomies
+
+  let(:callable_class) do
+    Class.new do
+      def disconnect; end
+    end
+  end
+  let(:callable_handle) { inventory::CallableHandle.new(handle_id: 'call:v1:test', callable: callable_class.new) }
+  let(:instance_key) { identity::InstanceKey.new(provider_family: 'vllm', instance_id: 'h200') }
+  let(:offering_id) { identity.offering_id(instance_key: instance_key, provider_native_key: 'gemma4') }
+  let(:lane_id) do
+    identity.lane_id(instance_key: instance_key, operation: :chat, model: 'gemma4', offering_id: offering_id)
+  end
+
+  def value_unknown
+    Legion::Extensions::Llm::Inventory::ValueEvidence.new(status: :unknown, source: :absent)
+  end
+
+  def full_operation_evidence(supported: [])
+    Legion::Extensions::Llm::Taxonomies::OPERATIONS.to_h do |op|
+      status, source = supported.include?(op) ? %i[supported provider_implementation] : %i[unknown absent]
+      [op, Legion::Extensions::Llm::Inventory::OperationEvidence.new(operation: op, status: status, source: source)]
+    end
+  end
+
+  def scalar_evidence_kwargs
+    {
+      context_evidence: value_unknown, max_output_evidence: value_unknown,
+      embedding_dimensions_evidence: value_unknown, model_revision_evidence: value_unknown,
+      tokenizer_evidence: value_unknown
+    }
+  end
+
+  def build_draft(**overrides)
+    Legion::Extensions::Llm::Inventory::OfferingDraft.new(
+      provider_native_key: 'gemma4', model: 'gemma4', tier: :local,
+      operation_evidence: full_operation_evidence(supported: %i[chat]),
+      publication_source: :provider_catalog, **scalar_evidence_kwargs, **overrides
+    )
+  end
+
+  def build_offering_record(**overrides)
+    Legion::Extensions::Llm::Inventory::OfferingRecord.new(
+      offering_id: offering_id, provider_native_key: 'gemma4', instance_key: instance_key, model: 'gemma4',
+      tier: :local, operation_evidence: full_operation_evidence(supported: %i[chat]), capability_evidence: {},
+      quota_domains: {}, metadata: {}, callable_handle: callable_handle, publication_source: :provider_catalog,
+      **scalar_evidence_kwargs, **overrides
+    )
+  end
+
+  describe inventory::OfferingDraft do
+    it 'builds a valid frozen draft' do
+      draft = build_draft
+      expect(draft).to be_frozen
+      expect(draft.model).to eq('gemma4')
+      expect(draft.operation_evidence).to be_frozen
+    end
+
+    it 'rejects an unknown kwarg' do
+      expect { build_draft(bogus: 1) }.to raise_error(ArgumentError)
+    end
+
+    it 'requires operation_evidence to contain every canonical operation exactly' do
+      incomplete = full_operation_evidence.except(:moderate)
+      expect { build_draft(operation_evidence: incomplete) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects an operation_evidence value whose operation mismatches its key' do
+      mismatched = full_operation_evidence
+      mismatched[:chat] = Legion::Extensions::Llm::Inventory::OperationEvidence.new(
+        operation: :embed, status: :supported, source: :provider_implementation
+      )
+      expect { build_draft(operation_evidence: mismatched) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects secret-like metadata keys at any nesting level' do
+      expect { build_draft(metadata: { api_key: 'x' }) }.to raise_error(errors::ValidationError)
+      expect { build_draft(metadata: { nested: [{ authorization_header: 'x' }] }) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a known context value that is not a positive Integer' do
+      bad = Legion::Extensions::Llm::Inventory::ValueEvidence.new(status: :known, value: 0, source: :model_metadata)
+      expect { build_draft(context_evidence: bad) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects unsorted embedding dimensions' do
+      bad = Legion::Extensions::Llm::Inventory::ValueEvidence.new(
+        status: :known, value: [1024, 512], source: :provider_catalog
+      )
+      expect { build_draft(embedding_dimensions_evidence: bad) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'freezes copied metadata deeply' do
+      draft = build_draft(metadata: { a: { b: [1] } })
+      expect(draft.metadata[:a][:b]).to be_frozen
+    end
+
+    it 'normalizes quota_domain keys to canonical operations' do
+      draft = build_draft(quota_domains: { 'chat' => 'domain-a' })
+      expect(draft.quota_domains).to eq(chat: 'domain-a')
+    end
+  end
+
+  describe inventory::OfferingRecord do
+    it 'validates offering_id reproduction and exposes operation views' do
+      record = build_offering_record
+      expect(record.supported_operations).to eq(%i[chat])
+      expect(record.operation_status(operation: :chat)).to eq(:supported)
+      expect(record.operation_status(operation: :embed)).to eq(:unknown)
+      expect(record.capability_status(capability: :vision)).to eq(:unknown)
+      expect(record.unknown_operations).to include(:embed)
+    end
+
+    it 'rejects an offering_id that does not reproduce' do
+      expect { build_offering_record(offering_id: "off:v1:#{'0' * 64}") }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a non-InstanceKey and a non-CallableHandle' do
+      expect { build_offering_record(instance_key: :vllm) }.to raise_error(errors::ValidationError)
+      expect { build_offering_record(callable_handle: Object.new) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'returns the quota domain for an operation' do
+      record = build_offering_record(quota_domains: { chat: 'domain-a' })
+      expect(record.quota_domain(operation: :chat)).to eq('domain-a')
+      expect(record.quota_domain(operation: :embed)).to be_nil
+    end
+  end
+
+  describe inventory::LaneRecord do
+    def build_lane(**overrides)
+      Legion::Extensions::Llm::Inventory::LaneRecord.new(
+        lane_id: lane_id, offering_id: offering_id, instance_key: instance_key, provider_family: :vllm,
+        instance_id: 'h200', model: 'gemma4', tier: :local, operation: :chat, capability_evidence: {},
+        quota_domain: nil, metadata: {}, callable_handle: callable_handle, publication_source: :provider_catalog,
+        **scalar_evidence_kwargs, **overrides
+      )
+    end
+
+    it 'builds a valid lane whose id reproduces' do
+      expect(build_lane.lane_id).to eq(lane_id)
+    end
+
+    it 'rejects provider_family/instance_id not equal to instance_key' do
+      expect { build_lane(instance_id: 'helios1') }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a lane_id that does not reproduce' do
+      expect { build_lane(lane_id: "lane:v1:#{'0' * 64}") }.to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe inventory::AvailabilityFact do
+    def build_fact(**overrides)
+      Legion::Extensions::Llm::Inventory::AvailabilityFact.new(
+        state: :available, availability_revision: 1, source: :startup_readiness, reason: 'activated', observed_at: nil,
+        **overrides
+      )
+    end
+
+    it 'accepts an available fact with nil unavailable_revision' do
+      expect(build_fact.state).to eq(:available)
+    end
+
+    it 'requires unavailable_revision to equal availability_revision when unavailable' do
+      expect { build_fact(state: :unavailable, availability_revision: 3, source: :dispatch, unavailable_revision: 2) }
+        .to raise_error(errors::ValidationError)
+      expect do
+        build_fact(state: :unavailable, availability_revision: 3, source: :dispatch, unavailable_revision: 3)
+      end.not_to raise_error
+    end
+
+    it 'rejects a non-unavailable state that carries an unavailable_revision' do
+      expect { build_fact(unavailable_revision: 1) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'requires both probe timestamps for a non-nil outcome and forbids completion before start' do
+      now = Time.now
+      expect { build_fact(last_probe_outcome: :success) }.to raise_error(errors::ValidationError)
+      expect do
+        build_fact(last_probe_outcome: :success, last_probe_started_at: now + 5, last_probe_completed_at: now)
+      end.to raise_error(errors::ValidationError)
+    end
+
+    it 'has no cooldown/half-open/latency fields' do
+      expect(build_fact.to_h.keys).to contain_exactly(
+        :state, :availability_revision, :source, :reason, :observed_at,
+        :last_probe_started_at, :last_probe_completed_at, :last_probe_outcome, :unavailable_revision
+      )
+    end
+  end
+
+  describe inventory::ReadinessResult do
+    it 'exposes ready? and rejects a non-boolean ready' do
+      result = Legion::Extensions::Llm::Inventory::ReadinessResult.new(ready: true, reason: 'ok')
+      expect(result).to be_ready
+      expect { Legion::Extensions::Llm::Inventory::ReadinessResult.new(ready: 'yes', reason: 'ok') }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects secret metadata' do
+      expect { Legion::Extensions::Llm::Inventory::ReadinessResult.new(ready: true, reason: 'ok', metadata: { secret: 'x' }) }
+        .to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe inventory::InstanceRecord do
+    def build_instance(**overrides)
+      Legion::Extensions::Llm::Inventory::InstanceRecord.new(
+        instance_key: instance_key, callable_handle: callable_handle,
+        availability: Legion::Extensions::Llm::Inventory::AvailabilityFact.new(
+          state: :available, availability_revision: 1, source: :startup_readiness, reason: 'activated', observed_at: nil
+        ),
+        offerings_by_id: { offering_id => build_offering_record },
+        publisher_id: 'pub:v1:x', publisher_token_id: 'ptok:v1:y', published_sequence: 1, published_at: Time.now,
+        **overrides
+      )
+    end
+
+    it 'builds an available instance with a complete offerings map' do
+      expect(build_instance.offerings_by_id).to be_frozen
+    end
+
+    it 'rejects an initializing availability' do
+      initializing = Legion::Extensions::Llm::Inventory::AvailabilityFact.new(
+        state: :initializing, availability_revision: 0, source: :startup_readiness, reason: 'claim', observed_at: nil
+      )
+      expect { build_instance(availability: initializing) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'accepts an explicit empty offerings map' do
+      expect(build_instance(offerings_by_id: {}).offerings_by_id).to eq({})
+    end
+  end
+
+  describe inventory::PublicationStatus do
+    it 'accepts initializing with a nil sequence and complete with a sequence' do
+      initializing = Legion::Extensions::Llm::Inventory::PublicationStatus.new(
+        instance_key: instance_key, state: :initializing, publisher_token_id: 'ptok:v1:x', published_sequence: nil
+      )
+      expect(initializing.state).to eq(:initializing)
+      complete = Legion::Extensions::Llm::Inventory::PublicationStatus.new(
+        instance_key: instance_key, state: :complete, publisher_token_id: 'ptok:v1:x', published_sequence: 2
+      )
+      expect(complete.published_sequence).to eq(2)
+    end
+
+    it 'rejects an invalid state' do
+      expect do
+        Legion::Extensions::Llm::Inventory::PublicationStatus.new(
+          instance_key: instance_key, state: :available, publisher_token_id: nil, published_sequence: nil
+        )
+      end.to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe inventory::MutationResult do
+    it 'accepts applied: true with a normal reason' do
+      result = Legion::Extensions::Llm::Inventory::MutationResult.new(
+        applied: true, reason: :activated, generation: 3, instance_key: instance_key
+      )
+      expect(result).to be_applied
+    end
+
+    it 'requires a stale/already-removed reason when applied is false' do
+      expect do
+        Legion::Extensions::Llm::Inventory::MutationResult.new(
+          applied: false, reason: :stale_publisher, generation: 3, instance_key: instance_key
+        )
+      end.not_to raise_error
+      expect do
+        Legion::Extensions::Llm::Inventory::MutationResult.new(
+          applied: false, reason: :activated, generation: 3, instance_key: instance_key
+        )
+      end.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a stale reason when applied is true' do
+      expect do
+        Legion::Extensions::Llm::Inventory::MutationResult.new(
+          applied: true, reason: :stale_publisher, generation: 3, instance_key: instance_key
+        )
+      end.to raise_error(errors::ValidationError)
+    end
+  end
+
+  it 'exposes taxonomies operations used by the records' do
+    expect(taxonomies::OPERATIONS).to include(:chat, :embed)
+  end
+end