lex-llm 0.6.16 → 0.7.0

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/evidence'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Evidence do
+  let(:errors) { Legion::Extensions::Llm::Inventory::Errors }
+  let(:operation_evidence) { Legion::Extensions::Llm::Inventory::OperationEvidence }
+  let(:capability_evidence) { Legion::Extensions::Llm::Inventory::CapabilityEvidence }
+  let(:value_evidence) { Legion::Extensions::Llm::Inventory::ValueEvidence }
+
+  describe 'OperationEvidence' do
+    it 'stores a canonical operation and exposes exact predicates' do
+      ev = operation_evidence.new(operation: :chat, status: :supported, source: :provider_implementation)
+      expect(ev.operation).to eq(:chat)
+      expect(ev).to be_supported
+      expect(ev).not_to be_unknown
+    end
+
+    it 'keeps stream_chat as the operation and never canonicalizes to capability streaming' do
+      ev = operation_evidence.new(operation: :stream_chat, status: :supported, source: :provider_catalog)
+      expect(ev.operation).to eq(:stream_chat)
+      expect(ev.operation).not_to eq(:streaming)
+    end
+
+    it 'rejects an operation alias when allow_aliases is false (registry path)' do
+      expect { operation_evidence.new(operation: :stream, status: :supported, source: :provider_catalog) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects an unknown operation' do
+      expect { operation_evidence.new(operation: :nonsense, status: :unknown, source: :absent) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a status outside supported/unsupported/unknown' do
+      expect { operation_evidence.new(operation: :chat, status: :maybe, source: :provider_implementation) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a source outside EVIDENCE_SOURCES' do
+      expect { operation_evidence.new(operation: :chat, status: :supported, source: :made_up) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'requires unknown status for an unknown-only source' do
+      expect { operation_evidence.new(operation: :chat, status: :supported, source: :default_false) }
+        .to raise_error(errors::ValidationError)
+      expect { operation_evidence.new(operation: :chat, status: :unknown, source: :default_false) }
+        .not_to raise_error
+    end
+
+    it 'freezes copied metadata' do
+      ev = operation_evidence.new(
+        operation: :chat, status: :supported, source: :provider_implementation, metadata: { note: +'x' }
+      )
+      expect(ev.metadata).to be_frozen
+      expect(ev.metadata[:note]).to be_frozen
+    end
+
+    it 'duplicates and freezes observed_at but rejects a non-Time' do
+      now = Time.now
+      ev = operation_evidence.new(operation: :chat, status: :supported, source: :probe, observed_at: now)
+      expect(ev.observed_at).to be_frozen
+      expect(ev.observed_at).not_to equal(now)
+      expect { operation_evidence.new(operation: :chat, status: :supported, source: :probe, observed_at: 5) }
+        .to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe 'CapabilityEvidence' do
+    it 'canonicalizes a capability alias' do
+      ev = capability_evidence.new(capability: :tool_use, status: :supported, source: :provider_implementation)
+      expect(ev.capability).to eq(:tools)
+    end
+
+    it 'canonicalizes the stream_chat capability alias to streaming (distinct from the operation)' do
+      ev = capability_evidence.new(capability: :stream_chat, status: :supported, source: :provider_catalog)
+      expect(ev.capability).to eq(:streaming)
+    end
+
+    it 'rejects a non-canonical capability' do
+      expect { capability_evidence.new(capability: :telepathy, status: :unknown, source: :absent) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'requires unknown status for guessed/default_false/failed_probe sources' do
+      %i[guessed default_false failed_probe inconclusive_probe].each do |source|
+        expect { capability_evidence.new(capability: :vision, status: :unsupported, source: source) }
+          .to raise_error(errors::ValidationError)
+        expect { capability_evidence.new(capability: :vision, status: :unknown, source: source) }
+          .not_to raise_error
+      end
+    end
+  end
+
+  describe 'ValueEvidence' do
+    it 'requires a non-nil value when known and copies/freezes it' do
+      ev = value_evidence.new(status: :known, value: 128_000, source: :model_metadata)
+      expect(ev).to be_known
+      expect(ev.value).to eq(128_000)
+    end
+
+    it 'freezes a known collection value' do
+      ev = value_evidence.new(status: :known, value: [512, 1024], source: :provider_catalog)
+      expect(ev.value).to be_frozen
+    end
+
+    it 'rejects a known status with a nil value' do
+      expect { value_evidence.new(status: :known, value: nil, source: :model_metadata) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'requires nil value when unknown' do
+      expect { value_evidence.new(status: :unknown, value: 5, source: :absent) }
+        .to raise_error(errors::ValidationError)
+      expect(value_evidence.new(status: :unknown, source: :absent)).to be_unknown
+    end
+
+    it 'enforces the unknown-only source rule' do
+      expect { value_evidence.new(status: :known, value: 10, source: :guessed) }
+        .to raise_error(errors::ValidationError)
+    end
+  end
+end

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

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/identity'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Identity do
+  let(:errors) { Legion::Extensions::Llm::Inventory::Errors }
+  let(:instance_key_class) { Legion::Extensions::Llm::Inventory::Identity::InstanceKey }
+
+  fixture_path = File.expand_path('../conformance/fixtures/ssot_identity_vectors.json', __dir__)
+  fixture = Legion::JSON.load(File.read(fixture_path))
+
+  def hex(binary)
+    binary.b.unpack1('H*')
+  end
+
+  describe 'binding identity vectors (recomputed field by field)' do
+    fixture[:vectors].each_with_index do |vector, index|
+      context "with vector #{index}: #{vector[:provider_family]}+#{vector[:instance_id]}" do
+        let(:instance_key) do
+          instance_key_class.new(
+            provider_family: vector[:provider_family],
+            instance_id: vector[:instance_id]
+          )
+        end
+
+        it 'reproduces every framed field as lowercase hex bytes' do
+          expect(hex(described_class.length_frame(value: instance_key.provider_family)))
+            .to eq(vector[:framed_hex][:provider_family])
+          expect(hex(described_class.length_frame(value: instance_key.instance_id)))
+            .to eq(vector[:framed_hex][:instance_id])
+          expect(hex(described_class.length_frame(value: vector[:provider_native_key])))
+            .to eq(vector[:framed_hex][:provider_native_key])
+          expect(hex(described_class.length_frame(value: vector[:operation])))
+            .to eq(vector[:framed_hex][:operation])
+          expect(hex(described_class.length_frame(value: vector[:model])))
+            .to eq(vector[:framed_hex][:model])
+        end
+
+        it 'reproduces the offering hash input and offering_id' do
+          input = described_class.length_frame(value: instance_key.provider_family) +
+                  described_class.length_frame(value: instance_key.instance_id) +
+                  described_class.length_frame(value: vector[:provider_native_key])
+          expect(hex(input)).to eq(vector[:offering_hash_input_hex])
+
+          offering_id = described_class.offering_id(
+            instance_key: instance_key, provider_native_key: vector[:provider_native_key]
+          )
+          expect(offering_id).to eq(vector[:expected_offering_id])
+        end
+
+        it 'reproduces the lane hash input and lane_id' do
+          offering_id = described_class.offering_id(
+            instance_key: instance_key, provider_native_key: vector[:provider_native_key]
+          )
+          input = "lane-v1\x00".b +
+                  described_class.length_frame(value: instance_key.provider_family) +
+                  described_class.length_frame(value: instance_key.instance_id) +
+                  described_class.length_frame(value: vector[:operation]) +
+                  described_class.length_frame(value: vector[:model]) +
+                  described_class.length_frame(value: offering_id)
+          expect(hex(input)).to eq(vector[:lane_hash_input_hex])
+
+          lane_id = described_class.lane_id(
+            instance_key: instance_key,
+            operation: vector[:operation].to_sym,
+            model: vector[:model],
+            offering_id: offering_id
+          )
+          expect(lane_id).to eq(vector[:expected_lane_id])
+        end
+
+        it 'validates the reproduced offering_id and lane_id' do
+          offering_id = vector[:expected_offering_id]
+          expect(
+            described_class.validate_offering_id!(
+              value: offering_id, instance_key: instance_key, provider_native_key: vector[:provider_native_key]
+            )
+          ).to eq(offering_id)
+          expect(
+            described_class.validate_lane_id!(
+              value: vector[:expected_lane_id], instance_key: instance_key,
+              operation: vector[:operation].to_sym, model: vector[:model], offering_id: offering_id
+            )
+          ).to eq(vector[:expected_lane_id])
+        end
+      end
+    end
+  end
+
+  describe 'independence and delimiter safety' do
+    it 'produces distinct offering/lane IDs for the same model on two instance IDs' do
+      expect(fixture[:vectors][0][:expected_offering_id]).not_to eq(fixture[:vectors][1][:expected_offering_id])
+      expect(fixture[:vectors][0][:expected_lane_id]).not_to eq(fixture[:vectors][1][:expected_lane_id])
+    end
+
+    it 'is tier-independent: tier is never a framing input' do
+      vector = fixture[:vectors][0]
+      instance_key = instance_key_class.new(provider_family: vector[:provider_family], instance_id: vector[:instance_id])
+      %i[local frontier].each do |_tier|
+        offering_id = described_class.offering_id(
+          instance_key: instance_key, provider_native_key: vector[:provider_native_key]
+        )
+        expect(offering_id).to eq(vector[:expected_offering_id])
+        expect(
+          described_class.lane_id(
+            instance_key: instance_key, operation: vector[:operation].to_sym,
+            model: vector[:model], offering_id: offering_id
+          )
+        ).to eq(vector[:expected_lane_id])
+      end
+    end
+
+    it 'frames punctuation inside a component without delimiter ambiguity' do
+      vector = fixture[:vectors][2]
+      instance_key = instance_key_class.new(provider_family: vector[:provider_family], instance_id: vector[:instance_id])
+      expect(instance_key.instance_id).to eq('prod:eastus')
+      expect(
+        described_class.offering_id(instance_key: instance_key, provider_native_key: vector[:provider_native_key])
+      ).to eq(vector[:expected_offering_id])
+    end
+  end
+
+  describe '.length_frame' do
+    it 'is decimal byte length + ASCII colon + exact UTF-8 bytes, in binary' do
+      frame = described_class.length_frame(value: 'gemma4')
+      expect(frame.encoding).to eq(Encoding::BINARY)
+      expect(frame).to eq('6:gemma4'.b)
+    end
+
+    it 'counts UTF-8 bytes, not characters' do
+      composed = [0x00e9].pack('U*') # single codepoint => two UTF-8 bytes
+      expect(described_class.length_frame(value: composed)).to eq('2:'.b + composed.b)
+    end
+  end
+
+  describe '.normalize_text' do
+    it 'accepts String and Symbol and returns a frozen UTF-8 String' do
+      result = described_class.normalize_text(value: :vllm, field: :provider_family)
+      expect(result).to eq('vllm')
+      expect(result).to be_frozen
+    end
+
+    it 'trims surrounding whitespace' do
+      expect(described_class.normalize_text(value: '  h200  ', field: :instance_id)).to eq('h200')
+    end
+
+    it 'rejects empty and whitespace-only values' do
+      expect { described_class.normalize_text(value: '   ', field: :f) }.to raise_error(errors::ValidationError)
+      expect { described_class.normalize_text(value: '', field: :f) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects invalid UTF-8' do
+      expect { described_class.normalize_text(value: "\xFF".b, field: :f) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a non-NFC (decomposed) string' do
+      decomposed = [0x0065, 0x0301].pack('U*') # e + combining acute; not NFC
+      expect { described_class.normalize_text(value: decomposed, field: :f) }
+        .to raise_error(errors::ValidationError, /NFC/)
+    end
+
+    it 'rejects a non-text type' do
+      expect { described_class.normalize_text(value: 5, field: :f) }.to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe '.normalize_enum' do
+    it 'returns an allowed symbol' do
+      expect(described_class.normalize_enum(value: 'local', field: :tier, allowed: %i[local frontier])).to eq(:local)
+    end
+
+    it 'rejects a value not in the allowed set' do
+      expect { described_class.normalize_enum(value: :nope, field: :tier, allowed: %i[local]) }
+        .to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe 'InstanceKey' do
+    it 'downcases provider_family to a Symbol and preserves instance_id case' do
+      key = instance_key_class.new(provider_family: 'Azure_Foundry', instance_id: 'Prod:EastUS')
+      expect(key.provider_family).to eq(:azure_foundry)
+      expect(key.instance_id).to eq('Prod:EastUS')
+    end
+
+    it 'exposes to_h with the two fields' do
+      key = instance_key_class.new(provider_family: :vllm, instance_id: 'h200')
+      expect(key.to_h).to eq(provider_family: :vllm, instance_id: 'h200')
+    end
+
+    it 'is value-equal for equal normalized fields' do
+      a = instance_key_class.new(provider_family: 'vllm', instance_id: 'h200')
+      b = instance_key_class.new(provider_family: :vllm, instance_id: '  h200 ')
+      expect(a).to eq(b)
+      expect(a.hash).to eq(b.hash)
+    end
+
+    it 'rejects a provider_family that is not snake-case ASCII' do
+      expect { instance_key_class.new(provider_family: '1bad', instance_id: 'x') }
+        .to raise_error(errors::ValidationError)
+      expect { instance_key_class.new(provider_family: 'has space', instance_id: 'x') }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects the reserved instance_id "default"' do
+      expect { instance_key_class.new(provider_family: 'vllm', instance_id: 'default') }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects nil fields' do
+      expect { instance_key_class.new(provider_family: nil, instance_id: 'x') }
+        .to raise_error(errors::ValidationError)
+      expect { instance_key_class.new(provider_family: 'vllm', instance_id: nil) }
+        .to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe 'public surface' do
+    it 'exposes exactly the seven documented module methods' do
+      expected = %i[
+        normalize_text normalize_enum length_frame offering_id lane_id
+        validate_offering_id! validate_lane_id!
+      ].sort
+      expect(described_class.singleton_methods(false).sort).to eq(expected)
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/immutable_value'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::ImmutableValue do
+  subject(:copy) { described_class.copy_and_freeze(value: value, field: :meta) }
+
+  describe 'scalar passthrough' do
+    it 'returns nil, booleans, symbols, and integers unchanged' do
+      [nil, true, false, :sym, 0, -5, 2**80].each do |scalar|
+        expect(described_class.copy_and_freeze(value: scalar, field: :f)).to eq(scalar)
+      end
+    end
+
+    it 'accepts finite floats' do
+      expect(described_class.copy_and_freeze(value: 1.5, field: :f)).to eq(1.5)
+    end
+
+    it 'rejects NaN' do
+      expect { described_class.copy_and_freeze(value: (0.0 / 0.0), field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /f is not a finite Float/)
+    end
+
+    it 'rejects positive and negative infinity' do
+      expect { described_class.copy_and_freeze(value: (1.0 / 0.0), field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+      expect { described_class.copy_and_freeze(value: (-1.0 / 0.0), field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+    end
+  end
+
+  describe 'strings' do
+    let(:value) { +'hello' }
+
+    it 'returns a frozen copy' do
+      expect(copy).to eq('hello')
+      expect(copy).to be_frozen
+    end
+
+    it 'does not retain the original mutable reference' do
+      original = +'mutable'
+      result = described_class.copy_and_freeze(value: original, field: :f)
+      expect(result).not_to equal(original)
+    end
+
+    it 'rejects invalid UTF-8' do
+      bad = "\xFF\xFE".b
+      expect { described_class.copy_and_freeze(value: bad, field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /not valid UTF-8/)
+    end
+  end
+
+  describe 'Time' do
+    let(:value) { Time.now }
+
+    it 'duplicates and freezes' do
+      original = Time.now
+      result = described_class.copy_and_freeze(value: original, field: :f)
+      expect(result).to eq(original)
+      expect(result).to be_frozen
+      expect(result).not_to equal(original)
+    end
+  end
+
+  describe 'arrays and hashes' do
+    it 'deeply freezes nested arrays preserving order' do
+      result = described_class.copy_and_freeze(value: [3, [2, [1]]], field: :f)
+      expect(result).to eq([3, [2, [1]]])
+      expect(result).to be_frozen
+      expect(result[1]).to be_frozen
+      expect(result[1][1]).to be_frozen
+    end
+
+    it 'deeply freezes nested hashes and preserves insertion order' do
+      result = described_class.copy_and_freeze(value: { b: 1, a: { c: [1] } }, field: :f)
+      expect(result.keys).to eq(%i[b a])
+      expect(result).to be_frozen
+      expect(result[:a]).to be_frozen
+      expect(result[:a][:c]).to be_frozen
+    end
+
+    it 'accepts String and Symbol hash keys and freezes String keys' do
+      result = described_class.copy_and_freeze(value: { 'x' => 1, y: 2 }, field: :f)
+      expect(result.keys.map(&:frozen?)).to all(be(true))
+    end
+
+    it 'rejects a non-String/Symbol hash key' do
+      expect { described_class.copy_and_freeze(value: { 1 => :v }, field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, %r{non-String/Symbol key})
+    end
+
+    it 'does not retain nested mutable references from the original' do
+      inner = +'inner'
+      original = { list: [inner] }
+      result = described_class.copy_and_freeze(value: original, field: :f)
+      inner << '-mutated'
+      expect(result[:list].first).to eq('inner')
+    end
+  end
+
+  describe 'rejections' do
+    it 'rejects an unsupported object' do
+      expect { described_class.copy_and_freeze(value: Object.new, field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /unsupported value type/)
+    end
+
+    it 'rejects a callable' do
+      expect { described_class.copy_and_freeze(value: -> { 1 }, field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /unsupported value type/)
+    end
+
+    it 'rejects a cyclic array naming the field path' do
+      cyclic = []
+      cyclic << cyclic
+      expect { described_class.copy_and_freeze(value: cyclic, field: :meta) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /meta.*cyclic/)
+    end
+
+    it 'rejects a cyclic hash' do
+      cyclic = {}
+      cyclic[:self] = cyclic
+      expect { described_class.copy_and_freeze(value: cyclic, field: :meta) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /cyclic/)
+    end
+
+    it 'allows the same non-cyclic object referenced twice' do
+      shared = { k: 1 }
+      expect { described_class.copy_and_freeze(value: [shared, shared], field: :f) }.not_to raise_error
+    end
+  end
+end

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