lex-llm 0.6.16 → 0.7.2

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/registry'
+require_relative '../../../../support/ssot_registry_helpers'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Registry do
+  include SsotRegistryHelpers
+
+  inventory = Legion::Extensions::Llm::Inventory
+  errors = inventory::Errors
+
+  before { described_class.reset! }
+
+  let(:key) { instance_key }
+  let(:callable) { fake_callable }
+  let(:coordinator) { probe_coordinator(key) }
+
+  describe 'empty boot snapshot' do
+    it 'exposes generation zero and no records' do
+      snapshot = described_class.snapshot
+      expect(snapshot.generation).to eq(0)
+      expect(snapshot.each_lane.to_a).to be_empty
+      expect(snapshot.each_offering.to_a).to be_empty
+      expect(snapshot.instance(instance_key: key)).to be_nil
+    end
+  end
+
+  describe 'claim' do
+    it 'shows an initializing publication status with no active model or callable' do
+      described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator)
+      snapshot = described_class.snapshot
+      status = snapshot.publication_status(instance_key: key)
+      expect(status.state).to eq(:initializing)
+      expect(snapshot.instance(instance_key: key)).to be_nil
+      expect(snapshot.lanes_for(instance_key: key)).to be_empty
+    end
+
+    it 'returns an opaque PublisherToken' do
+      token = described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator)
+      expect(token).to be_a(inventory::PublisherToken)
+    end
+
+    it 'rejects reusing the exact same callable object on re-claim' do
+      described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator)
+      expect { described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'fences the superseded token after a fresh re-claim with a distinct callable' do
+      token1 = described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator)
+      described_class.claim_instance(instance_key: key, callable: fake_callable, probe_request_handle: coordinator)
+      expect { described_class.readiness_probe_started(instance_key: key, publisher_token: token1) }
+        .to raise_error(errors::FencedPublisherError)
+    end
+  end
+
+  describe 'startup activation sequence' do
+    it 'raises if readiness_succeeded is called before activation' do
+      token = described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator)
+      probe = described_class.readiness_probe_started(instance_key: key, publisher_token: token)
+      expect { described_class.readiness_succeeded(instance_key: key, probe_token: probe) }
+        .to raise_error(errors::InvalidTransitionError)
+    end
+
+    it 'atomically publishes callable, offerings, lanes, and available on activation' do
+      claim_and_activate(key: key, callable: callable, coordinator: coordinator)
+      snapshot = described_class.snapshot
+      record = snapshot.instance(instance_key: key)
+      expect(record).not_to be_nil
+      expect(record.availability.state).to eq(:available)
+      expect(snapshot.lanes_for(instance_key: key).size).to eq(1)
+      expect(snapshot.offerings_for(instance_key: key).size).to eq(1)
+      expect(snapshot.publication_status(instance_key: key).state).to eq(:complete)
+    end
+
+    it 'accepts an explicit complete empty activation as complete, not initializing' do
+      token = described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator)
+      probe = described_class.readiness_probe_started(instance_key: key, publisher_token: token)
+      result = described_class.activate_instance_snapshot(
+        publisher_token: token, instance_key: key, offerings: [], sequence: 0, probe_token: probe
+      )
+      expect(result.applied).to be(true)
+      snapshot = described_class.snapshot
+      expect(snapshot.publication_status(instance_key: key).state).to eq(:complete)
+      expect(snapshot.instance(instance_key: key).offerings_by_id).to eq({})
+    end
+
+    it 'consumes the probe token so it cannot be reused' do
+      token = described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator)
+      probe = described_class.readiness_probe_started(instance_key: key, publisher_token: token)
+      described_class.activate_instance_snapshot(publisher_token: token, instance_key: key, offerings: drafts, sequence: 0, probe_token: probe)
+      expect { described_class.readiness_succeeded(instance_key: key, probe_token: probe) }
+        .to raise_error(errors::InvalidProbeError)
+    end
+
+    it 'requires a sequence greater than the claim baseline' do
+      token = described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator)
+      probe = described_class.readiness_probe_started(instance_key: key, publisher_token: token)
+      expect do
+        described_class.activate_instance_snapshot(publisher_token: token, instance_key: key, offerings: drafts, sequence: -1, probe_token: probe)
+      end.to raise_error(errors::StaleSequenceError)
+    end
+
+    it 'increments generation once for a claim' do
+      generation = described_class.snapshot.generation
+      described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator)
+      expect(described_class.snapshot.generation).to eq(generation + 1)
+    end
+  end
+
+  describe 'initial readiness failure' do
+    it 'leaves the instance initializing, exposes no model/callable, and does not mark unavailable' do
+      token = described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: coordinator)
+      probe = described_class.readiness_probe_started(instance_key: key, publisher_token: token)
+      result = described_class.readiness_failed(instance_key: key, probe_token: probe, reason: 'probe failed')
+      expect(result.applied).to be(true)
+      expect(result.reason).to eq(:initial_readiness_failed)
+      snapshot = described_class.snapshot
+      expect(snapshot.instance(instance_key: key)).to be_nil
+      expect(snapshot.publication_status(instance_key: key).state).to eq(:initializing)
+      expect(snapshot.lanes_for(instance_key: key)).to be_empty
+    end
+  end
+
+  describe 'no external calls under the mutation mutex' do
+    it 'never invokes the callable disconnect or a probe enqueue while activating' do
+      enqueue_calls = []
+      probing = probe_coordinator(key, enqueue: lambda { |request:|
+        enqueue_calls << request
+        true
+      })
+      token = described_class.claim_instance(instance_key: key, callable: callable, probe_request_handle: probing)
+      probe = described_class.readiness_probe_started(instance_key: key, publisher_token: token)
+      described_class.activate_instance_snapshot(publisher_token: token, instance_key: key, offerings: drafts, sequence: 0, probe_token: probe)
+      expect(callable.disconnect_count).to eq(0)
+      expect(enqueue_calls).to be_empty
+    end
+  end
+end

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

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/registry'
+require_relative '../../../../support/ssot_registry_helpers'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Registry do
+  include SsotRegistryHelpers
+
+  errors = Legion::Extensions::Llm::Inventory::Errors
+
+  before { described_class.reset! }
+
+  let(:key_a) { instance_key(instance: 'h200') }
+  let(:key_b) { instance_key(instance: 'helios1') }
+
+  def revision_of(key)
+    described_class.snapshot.instance(instance_key: key)&.availability&.availability_revision
+  end
+
+  def state_of(key)
+    described_class.snapshot.instance(instance_key: key)&.availability&.state
+  end
+
+  def probe(token, key)
+    described_class.readiness_probe_started(instance_key: key, publisher_token: token)
+  end
+
+  describe 'ordinary readiness success while available' do
+    it 'records telemetry without changing availability revision or eligibility' do
+      token = claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      expect(revision_of(key_a)).to eq(1)
+      result = described_class.readiness_succeeded(instance_key: key_a, probe_token: probe(token, key_a))
+      expect(result.reason).to eq(:readiness_observed)
+      expect(revision_of(key_a)).to eq(1)
+      expect(state_of(key_a)).to eq(:available)
+    end
+  end
+
+  describe 'exact-instance isolation' do
+    it 'keeps two instances of the same provider and model independent through failure and recovery' do
+      token_a = claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      claim_and_activate(key: key_b, callable: fake_callable, coordinator: probe_coordinator(key_b))
+
+      described_class.readiness_failed(instance_key: key_a, probe_token: probe(token_a, key_a), reason: 'a failed')
+      expect(state_of(key_a)).to eq(:unavailable)
+      expect(state_of(key_b)).to eq(:available)
+
+      recover = described_class.readiness_succeeded(instance_key: key_a, probe_token: probe(token_a, key_a))
+      expect(recover.reason).to eq(:instance_recovered)
+      expect(state_of(key_a)).to eq(:available)
+      expect(state_of(key_b)).to eq(:available)
+    end
+  end
+
+  describe 'availability revisions' do
+    it 'increments the availability revision on each successive unavailable transition' do
+      token = claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      described_class.readiness_failed(instance_key: key_a, probe_token: probe(token, key_a), reason: 'first')
+      first = revision_of(key_a)
+      described_class.readiness_failed(instance_key: key_a, probe_token: probe(token, key_a), reason: 'second')
+      expect(revision_of(key_a)).to eq(first + 1)
+    end
+  end
+
+  describe 'stale and superseded probes cannot recover' do
+    it 'refuses recovery from a probe started before the failure' do
+      token = claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      stale = probe(token, key_a) # started at availability revision 1, before the failure
+      described_class.readiness_failed(instance_key: key_a, probe_token: probe(token, key_a), reason: 'failed')
+      result = described_class.readiness_succeeded(instance_key: key_a, probe_token: stale)
+      expect(result.applied).to be(false)
+      expect(result.reason).to eq(:stale_probe)
+      expect(state_of(key_a)).to eq(:unavailable)
+    end
+
+    it 'recovers with a probe started after the failure' do
+      token = claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      described_class.readiness_failed(instance_key: key_a, probe_token: probe(token, key_a), reason: 'failed')
+      fresh = probe(token, key_a) # started at the new (unavailable) revision
+      result = described_class.readiness_succeeded(instance_key: key_a, probe_token: fresh)
+      expect(result.reason).to eq(:instance_recovered)
+      expect(state_of(key_a)).to eq(:available)
+    end
+  end
+
+  describe 'dispatch-reported instance unavailable' do
+    it 'marks only the exact active instance unavailable using the non-secret token id and enqueues a probe' do
+      enqueued = []
+      coordinator_a = probe_coordinator(key_a, enqueue: lambda { |request:|
+        enqueued << request
+        true
+      })
+      token_a = claim_and_activate(key: key_a, callable: fake_callable, coordinator: coordinator_a)
+      claim_and_activate(key: key_b, callable: fake_callable, coordinator: probe_coordinator(key_b))
+
+      result = described_class.dispatch_instance_unavailable(
+        instance_key: key_a, publisher_token_id: token_a.publisher_token_id, reason: 'normalized instance_unavailable'
+      )
+      expect(result.applied).to be(true)
+      expect(result.reason).to eq(:instance_unavailable)
+      expect(state_of(key_a)).to eq(:unavailable)
+      expect(state_of(key_b)).to eq(:available)
+      expect(enqueued.size).to eq(1)
+      expect(enqueued.first.instance_key).to eq(key_a)
+    end
+
+    it 'rejects a stale (non-current) publisher token id without mutating' do
+      claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      result = described_class.dispatch_instance_unavailable(
+        instance_key: key_a, publisher_token_id: 'ptok:v1:not-current', reason: 'x'
+      )
+      expect(result.applied).to be(false)
+      expect(result.reason).to eq(:stale_publisher)
+      expect(state_of(key_a)).to eq(:available)
+    end
+
+    it 'is a process-local method that accepts the public token id, not the secret PublisherToken' do
+      token = claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      # Passing the secret token object where a String id is expected must not authorize the transition.
+      result = described_class.dispatch_instance_unavailable(
+        instance_key: key_a, publisher_token_id: token, reason: 'x'
+      )
+      expect(result.applied).to be(false)
+      expect(state_of(key_a)).to eq(:available)
+    end
+
+    it 'is invalid for an initializing instance' do
+      token = described_class.claim_instance(instance_key: key_a, callable: fake_callable, probe_request_handle: probe_coordinator(key_a))
+      expect do
+        described_class.dispatch_instance_unavailable(instance_key: key_a, publisher_token_id: token.publisher_token_id, reason: 'x')
+      end.to raise_error(errors::InvalidTransitionError)
+    end
+  end
+
+  describe 'global instance-unavailable filters all of that instance lanes' do
+    it 'marks every lane of one instance unavailable without touching another instance' do
+      two_models = drafts(native: 'gemma4', model: 'gemma4') +
+                   drafts(native: 'gemma5', model: 'gemma5')
+      token_a = described_class.claim_instance(instance_key: key_a, callable: fake_callable, probe_request_handle: probe_coordinator(key_a))
+      probe_a = described_class.readiness_probe_started(instance_key: key_a, publisher_token: token_a)
+      described_class.activate_instance_snapshot(publisher_token: token_a, instance_key: key_a, offerings: two_models, sequence: 0, probe_token: probe_a)
+      claim_and_activate(key: key_b, callable: fake_callable, coordinator: probe_coordinator(key_b))
+
+      described_class.dispatch_instance_unavailable(instance_key: key_a, publisher_token_id: token_a.publisher_token_id, reason: 'down')
+      expect(state_of(key_a)).to eq(:unavailable)
+      # lanes remain visible for diagnosis on the instance record
+      expect(described_class.snapshot.lanes_for(instance_key: key_a).size).to eq(2)
+      expect(state_of(key_b)).to eq(:available)
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/registry'
+require_relative '../../../../support/ssot_registry_helpers'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Registry do
+  include SsotRegistryHelpers
+
+  errors = Legion::Extensions::Llm::Inventory::Errors
+
+  before { described_class.reset! }
+
+  let(:key) { instance_key }
+  let(:callable) { fake_callable }
+  let(:coordinator) { probe_coordinator(key) }
+  let(:token) { claim_and_activate(key: key, callable: callable, coordinator: coordinator) }
+  let(:handle) { token && described_class.snapshot.instance(instance_key: key).callable_handle }
+
+  it 'acquires a lease that exposes the exact captured callable' do
+    lease = described_class.acquire(callable_handle: handle)
+    expect(lease.callable).to equal(callable)
+    lease.release
+  end
+
+  it 'rejects acquiring a non-CallableHandle' do
+    token
+    expect { described_class.acquire(callable_handle: Object.new) }.to raise_error(errors::UnknownCallableError)
+  end
+
+  it 'lets an already-acquired lease finish after the instance is removed, disconnecting exactly once' do
+    lease = described_class.acquire(callable_handle: handle)
+    described_class.remove_instance(instance_key: key, publisher_token: token)
+    expect(handle.state).to eq(:retiring)
+    expect(callable.disconnect_count).to eq(0)
+    # the in-flight lease still works
+    expect(lease.callable).to equal(callable)
+    lease.release
+    expect(handle.state).to eq(:disposed)
+    expect(callable.disconnect_count).to eq(1)
+  end
+
+  it 'blocks a new acquisition against a retired handle' do
+    described_class.acquire(callable_handle: handle) # keep one lease so removal leaves it retiring
+    described_class.remove_instance(instance_key: key, publisher_token: token)
+    expect { described_class.acquire(callable_handle: handle) }.to raise_error(errors::StaleCallableError)
+  end
+
+  it 'removes an idle instance and disposes its handle' do
+    handle
+    described_class.remove_instance(instance_key: key, publisher_token: token)
+    expect(handle.state).to eq(:disposed)
+    expect(described_class.snapshot.instance(instance_key: key)).to be_nil
+  end
+
+  it 'returns already_removed for a second removal' do
+    handle
+    described_class.remove_instance(instance_key: key, publisher_token: token)
+    result = described_class.remove_instance(instance_key: key, publisher_token: token)
+    expect(result.applied).to be(false)
+    expect(result.reason).to eq(:already_removed)
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/registry'
+require_relative '../../../../support/ssot_registry_helpers'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Registry do
+  include SsotRegistryHelpers
+
+  errors = Legion::Extensions::Llm::Inventory::Errors
+
+  before { described_class.reset! }
+
+  let(:key) { instance_key }
+  let(:callable) { fake_callable }
+  let(:coordinator) { probe_coordinator(key) }
+  let(:token) { claim_and_activate(key: key, callable: callable, coordinator: coordinator, sequence: 0) }
+
+  it 'replaces the complete offering set with a strictly increasing sequence' do
+    token
+    result = described_class.replace_instance_snapshot(
+      publisher_token: token, instance_key: key, offerings: drafts(native: 'gemma5', model: 'gemma5'), sequence: 1
+    )
+    expect(result.applied).to be(true)
+    expect(result.reason).to eq(:snapshot_replaced)
+    offerings = described_class.snapshot.offerings_for(instance_key: key)
+    expect(offerings.map(&:provider_native_key)).to eq(['gemma5'])
+  end
+
+  it 'preserves the exact availability fact across replacement' do
+    token
+    before_fact = described_class.snapshot.instance(instance_key: key).availability
+    described_class.replace_instance_snapshot(publisher_token: token, instance_key: key, offerings: drafts, sequence: 1)
+    after_fact = described_class.snapshot.instance(instance_key: key).availability
+    expect(after_fact.availability_revision).to eq(before_fact.availability_revision)
+    expect(after_fact.state).to eq(:available)
+  end
+
+  it 'rejects a non-increasing sequence' do
+    token
+    expect { described_class.replace_instance_snapshot(publisher_token: token, instance_key: key, offerings: drafts, sequence: 0) }
+      .to raise_error(errors::StaleSequenceError)
+  end
+
+  it 'treats an empty array as an authoritative complete empty snapshot' do
+    token
+    described_class.replace_instance_snapshot(publisher_token: token, instance_key: key, offerings: [], sequence: 1)
+    expect(described_class.snapshot.offerings_for(instance_key: key)).to be_empty
+    expect(described_class.snapshot.instance(instance_key: key).availability.state).to eq(:available)
+  end
+
+  it 'leaves the prior root untouched when draft validation fails' do
+    token
+    generation = described_class.snapshot.generation
+    duplicate = drafts + drafts # two drafts with the same provider_native_key
+    expect { described_class.replace_instance_snapshot(publisher_token: token, instance_key: key, offerings: duplicate, sequence: 1) }
+      .to raise_error(errors::ValidationError)
+    expect(described_class.snapshot.generation).to eq(generation)
+    expect(described_class.snapshot.offerings_for(instance_key: key).size).to eq(1)
+  end
+
+  it 'returns a stale publisher result for a superseded token' do
+    token
+    described_class.claim_instance(instance_key: key, callable: fake_callable, probe_request_handle: coordinator)
+    result = described_class.replace_instance_snapshot(publisher_token: token, instance_key: key, offerings: drafts, sequence: 5)
+    expect(result.applied).to be(false)
+    expect(result.reason).to eq(:stale_publisher)
+  end
+end

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

@@ -2,6 +2,8 @@
 
 require 'spec_helper'
 require 'legion/extensions/llm/inventory/scoped_refresher'
+require 'legion/extensions/llm/inventory/registry'
+require_relative '../../../../support/ssot_registry_helpers'
 
 RSpec.describe Legion::Extensions::Llm::Inventory::ScopedRefresher do
   describe '.compose_id' do
@@ -206,4 +208,130 @@ RSpec.describe Legion::Extensions::Llm::Inventory::ScopedRefresher do
       expect(cache_store).not_to have_key(cooldown_key)
     end
   end
+
+  describe Legion::Extensions::Llm::Inventory::ScopedRefresher::LegacyCoordinatorAdapter do
+    include SsotRegistryHelpers
+
+    inventory = Legion::Extensions::Llm::Inventory
+    errors = inventory::Errors
+
+    let(:fake_inventory) do
+      Class.new do
+        attr_reader :lanes
+
+        def initialize
+          @lanes = {}
+        end
+
+        def write_lane(lane:, **)
+          @lanes[lane[:id]] = lane
+          lane
+        end
+
+        def delete_lane(id:, **)
+          @lanes.delete(id)
+          :deleted
+        end
+
+        def lanes_for(provider:, instance:, **)
+          @lanes.values.select { |l| l[:provider_family].to_s == provider.to_s && l[:instance_id].to_s == instance.to_s }
+        end
+      end.new
+    end
+
+    let(:key) { instance_key(family: 'vllm', instance: 'h200') }
+    let(:adapter) { described_class.new(provider_family: :vllm) }
+
+    before do
+      inventory::Registry.reset!
+      stub_const('Legion::LLM::Inventory', fake_inventory)
+    end
+
+    def activate_chat
+      claim_and_activate(key: key, callable: fake_callable, coordinator: probe_coordinator(key))
+      Legion::Extensions::Llm::Inventory::Registry.snapshot
+    end
+
+    it 'projects an available instance into an exact five-field legacy lane and round-trips' do
+      result = adapter.sync_snapshot(snapshot: activate_chat, instance_key: key, mutation_reason: :activated)
+      expect(result).to eq(:applied)
+
+      legacy_id = 'local:vllm:h200:inference:gemma4'
+      expect(fake_inventory.lanes).to have_key(legacy_id)
+      lane = fake_inventory.lanes[legacy_id]
+      expect(lane[:id]).to eq(legacy_id)
+      expect(lane[:provider_instance]).to eq('h200')
+      expect(lane[:enabled]).to be(true)
+      expect(lane[:capabilities]).to include(:completion)
+      expect(lane[:metadata]).to include(ssot_v3_compatibility_projection: true)
+      round_trip = fake_inventory.lanes_for(provider: :vllm, instance: 'h200', type: :inference, model: 'gemma4')
+      expect(round_trip.map { |l| l[:id] }).to eq([legacy_id])
+    end
+
+    it 'deletes the old projection when the instance is removed (desired set empty)' do
+      token = claim_and_activate(key: key, callable: fake_callable, coordinator: probe_coordinator(key))
+      adapter.sync_snapshot(snapshot: inventory::Registry.snapshot, instance_key: key, mutation_reason: :activated)
+      expect(fake_inventory.lanes).not_to be_empty
+
+      inventory::Registry.remove_instance(instance_key: key, publisher_token: token)
+      adapter.sync_snapshot(snapshot: inventory::Registry.snapshot, instance_key: key, mutation_reason: :removed)
+      expect(fake_inventory.lanes).to be_empty
+    end
+
+    it 'deletes the old projection when the instance becomes unavailable' do
+      token = claim_and_activate(key: key, callable: fake_callable, coordinator: probe_coordinator(key))
+      adapter.sync_snapshot(snapshot: inventory::Registry.snapshot, instance_key: key, mutation_reason: :activated)
+      inventory::Registry.dispatch_instance_unavailable(instance_key: key, publisher_token_id: token.publisher_token_id, reason: 'down')
+      adapter.sync_snapshot(snapshot: inventory::Registry.snapshot, instance_key: key, mutation_reason: :instance_unavailable)
+      expect(fake_inventory.lanes).to be_empty
+    end
+
+    it 'fails closed and omits an ambiguous group that collapses multiple offerings' do
+      token = inventory::Registry.claim_instance(instance_key: key, callable: fake_callable, probe_request_handle: probe_coordinator(key))
+      probe = inventory::Registry.readiness_probe_started(instance_key: key, publisher_token: token)
+      two = drafts(native: 'a', model: 'gemma4') + drafts(native: 'b', model: 'gemma4')
+      inventory::Registry.activate_instance_snapshot(publisher_token: token, instance_key: key, offerings: two, sequence: 0, probe_token: probe)
+      adapter.sync_snapshot(snapshot: inventory::Registry.snapshot, instance_key: key, mutation_reason: :activated)
+      expect(fake_inventory.lanes).to be_empty
+    end
+
+    it 'returns :not_loaded when Legion::LLM::Inventory is absent' do
+      hide_const('Legion::LLM::Inventory')
+      expect(adapter.sync_snapshot(snapshot: activate_chat, instance_key: key, mutation_reason: :activated)).to eq(:not_loaded)
+    end
+
+    it 'rejects a different provider family, an invalid snapshot, and an unknown reason' do
+      snapshot = activate_chat
+      other = instance_key(family: 'openai', instance: 'h200')
+      expect { adapter.sync_snapshot(snapshot: snapshot, instance_key: other, mutation_reason: :activated) }
+        .to raise_error(errors::ValidationError)
+      expect { adapter.sync_snapshot(snapshot: {}, instance_key: key, mutation_reason: :activated) }
+        .to raise_error(errors::ValidationError)
+      expect { adapter.sync_snapshot(snapshot: snapshot, instance_key: key, mutation_reason: :made_up) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'returns :failed and preserves the prior tracked set when a write raises' do
+      snapshot = activate_chat
+      allow(fake_inventory).to receive(:write_lane).and_raise(StandardError, 'coordinator down')
+      expect(adapter.sync_snapshot(snapshot: snapshot, instance_key: key, mutation_reason: :activated)).to eq(:failed)
+    end
+
+    it 'never lets an old five-part id be accepted as a canonical lane:v1: identity' do
+      offering_id = inventory::Identity.offering_id(instance_key: key, provider_native_key: 'gemma4')
+      expect do
+        inventory::Identity.validate_lane_id!(
+          value: 'local:vllm:h200:inference:gemma4', instance_key: key,
+          operation: :chat, model: 'gemma4', offering_id: offering_id
+        )
+      end.to raise_error(errors::ValidationError)
+    end
+
+    it 'leaves the new Registry unchanged when the legacy projection runs' do
+      snapshot = activate_chat
+      generation = inventory::Registry.snapshot.generation
+      adapter.sync_snapshot(snapshot: snapshot, instance_key: key, mutation_reason: :activated)
+      expect(inventory::Registry.snapshot.generation).to eq(generation)
+    end
+  end
 end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/registry'
+require_relative '../../../../support/ssot_registry_helpers'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Snapshot do
+  include SsotRegistryHelpers
+
+  registry = Legion::Extensions::Llm::Inventory::Registry
+
+  before { registry.reset! }
+
+  let(:key_a) { instance_key(instance: 'h200') }
+  let(:key_b) { instance_key(instance: 'helios1') }
+
+  def activate_both
+    claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+    claim_and_activate(key: key_b, callable: fake_callable, coordinator: probe_coordinator(key_b))
+    registry.snapshot
+  end
+
+  describe 'lookups' do
+    it 'returns the frozen record or nil and never synthesizes a default' do
+      snapshot = activate_both
+      record = snapshot.instance(instance_key: key_a)
+      expect(record).to be_frozen
+      expect(snapshot.instance(instance_key: instance_key(instance: 'absent'))).to be_nil
+      expect(snapshot.lane(lane_id: 'lane:v1:missing')).to be_nil
+      expect(snapshot.offering(offering_id: 'off:v1:missing')).to be_nil
+    end
+
+    it 'only lists activated instances but keeps initializing claims in publication status' do
+      claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      registry.claim_instance(instance_key: key_b, callable: fake_callable, probe_request_handle: probe_coordinator(key_b))
+      snapshot = registry.snapshot
+      expect(snapshot.instance(instance_key: key_a)).not_to be_nil
+      expect(snapshot.instance(instance_key: key_b)).to be_nil
+      expect(snapshot.publication_status(instance_key: key_b).state).to eq(:initializing)
+    end
+  end
+
+  describe 'ordering and iteration' do
+    it 'returns frozen lanes_for/offerings_for arrays ordered by id' do
+      snapshot = activate_both
+      lanes = snapshot.lanes_for(instance_key: key_a)
+      expect(lanes).to be_frozen
+      expect(lanes.map(&:lane_id)).to eq(lanes.map(&:lane_id).sort)
+    end
+
+    it 'each_lane/each_offering yield in id order and return an Enumerator without a block' do
+      snapshot = activate_both
+      expect(snapshot.each_lane).to be_a(Enumerator)
+      expect(snapshot.each_offering).to be_a(Enumerator)
+      expect(snapshot.each_lane.map(&:lane_id)).to eq(snapshot.each_lane.map(&:lane_id).sort)
+    end
+  end
+
+  describe 'each_instance and each_publication_status' do
+    it 'return an Enumerator without a block' do
+      snapshot = activate_both
+      expect(snapshot.each_instance).to be_a(Enumerator)
+      expect(snapshot.each_publication_status).to be_a(Enumerator)
+    end
+
+    it 'yield immutable instance records in canonical InstanceKey order' do
+      snapshot = activate_both
+      records = snapshot.each_instance.to_a
+      expect(records.map { |record| record.instance_key.instance_id }).to eq(%w[h200 helios1])
+      expect(records).to all(be_a(Legion::Extensions::Llm::Inventory::InstanceRecord))
+      expect(records).to all(be_frozen)
+    end
+
+    it 'include initializing claims in each_publication_status but not each_instance' do
+      claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      registry.claim_instance(instance_key: key_b, callable: fake_callable, probe_request_handle: probe_coordinator(key_b))
+      snapshot = registry.snapshot
+      status_states = snapshot.each_publication_status.map(&:state)
+      expect(status_states).to contain_exactly(:complete, :initializing)
+      expect(snapshot.each_instance.map(&:instance_key)).to eq([key_a])
+    end
+
+    it 'does not expose either backing Hash' do
+      snapshot = activate_both
+      expect(snapshot).not_to respond_to(:instances_by_key)
+      expect(snapshot).not_to respond_to(:publication_status_by_key)
+    end
+  end
+
+  describe 'structural immutability of an older snapshot' do
+    it 'does not observe a later record or generation mutation' do
+      claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      old = registry.snapshot
+      old_generation = old.generation
+      claim_and_activate(key: key_b, callable: fake_callable, coordinator: probe_coordinator(key_b))
+      expect(old.generation).to eq(old_generation)
+      expect(old.instance(instance_key: key_b)).to be_nil
+      expect(registry.snapshot.instance(instance_key: key_b)).not_to be_nil
+    end
+
+    it 'lets a captured callable handle move to retiring after fencing (lifecycle exception)' do
+      token = claim_and_activate(key: key_a, callable: fake_callable, coordinator: probe_coordinator(key_a))
+      captured = registry.snapshot.instance(instance_key: key_a).callable_handle
+      expect(captured.state).to eq(:active)
+      registry.remove_instance(instance_key: key_a, publisher_token: token)
+      expect(captured.state).to eq(:disposed)
+    end
+  end
+end