lex-llm 0.7.3 → 0.8.0

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

@@ -3,209 +3,239 @@
 require 'spec_helper'
 
 RSpec.describe Legion::Extensions::Llm::StreamAccumulator do
-  describe '#add' do
-    it 'handles tool call deltas that omit arguments' do
-      accumulator = described_class.new
-      tool_call = Legion::Extensions::Llm::ToolCall.new(id: 'call_1', name: 'weather', arguments: nil)
-      chunk = Legion::Extensions::Llm::Chunk.new(role: :assistant, content: nil, tool_calls: { 'call_1' => tool_call })
+  let(:canonical) { Legion::Extensions::Llm::Canonical }
 
-      expect { accumulator.add(chunk) }.not_to raise_error
+  def text_chunk(delta)
+    canonical::Chunk.text_delta(delta: delta, request_id: 'req-1')
+  end
 
-      message = accumulator.to_message(nil)
-      expect(message.tool_calls['call_1'].arguments).to eq({})
-    end
+  def thinking_chunk(delta, signature: nil)
+    canonical::Chunk.thinking_delta(delta: delta, request_id: 'req-1', signature:)
+  end
 
-    it 'drops malformed accumulated tool arguments instead of raising' do
-      accumulator = described_class.new
-      tool_call = Legion::Extensions::Llm::ToolCall.new(id: 'call_1', name: 'weather', arguments: '{"city"')
-      chunk = Legion::Extensions::Llm::Chunk.new(role: :assistant, content: nil, tool_calls: { 'call_1' => tool_call })
+  def tool_fragment(id: nil, name: nil, arguments: '', index: nil, signature: nil)
+    canonical::Chunk.tool_call_delta(tool_call: { id:, name:, arguments:, index:, signature: }, request_id: 'req-1')
+  end
 
-      expect { accumulator.add(chunk) }.not_to raise_error
+  describe 'canonical chunk consumption (05 O5)' do
+    it 'emits text deltas and accumulates the final text' do
+      accumulator = described_class.new
+      emitted = accumulator.add(text_chunk('hello '))
+      emitted.concat(accumulator.add(text_chunk('world')))
+      response = accumulator.to_response(model: 'm')
 
-      message = accumulator.to_message(nil)
-      expect(message.tool_calls['call_1'].arguments).to eq({})
+      expect(emitted.map { |c| [c.type, c.delta] }).to eq([[:text_delta, 'hello '], [:text_delta, 'world']])
+      expect(response.text).to eq('hello world')
     end
 
-    it 'treats content before an unmatched closing think tag as thinking' do
+    it 'emits provider thinking deltas and carries the signature into the response' do
       accumulator = described_class.new
-      chunk = Legion::Extensions::Llm::Chunk.new(
-        role: :assistant,
-        content: "internal\n</think>\n\nHello"
-      )
+      emitted = accumulator.add(thinking_chunk('hmm ', signature: 'sig-1'))
+      response = accumulator.to_response(model: 'm')
 
-      accumulator.add(chunk)
-
-      message = accumulator.to_message(nil)
-      expect(message.content).to eq('Hello')
-      expect(message.thinking.text).to eq("internal\n")
+      expect(emitted.map { |c| [c.type, c.delta] }).to eq([[:thinking_delta, 'hmm ']])
+      expect(response.thinking.content).to eq('hmm ')
+      expect(response.thinking.signature).to eq('sig-1')
     end
 
-    it 'does not leak streamed thinking tag variants split across chunks' do
+    it 'passes tool_call_delta chunks through and accumulates fragments' do
       accumulator = described_class.new
-      stream = ['<thinking>', 'internal', '</thinking>Hello']
-
-      filtered = stream.filter_map do |content|
-        chunk = Legion::Extensions::Llm::Chunk.new(role: :assistant, content: content)
-        accumulator.add(chunk)
-        accumulator.filtered_chunk(chunk)
-      end
+      emitted = accumulator.add(tool_fragment(id: 'call-1', name: 'f', arguments: '{"a"'))
+      emitted.concat(accumulator.add(tool_fragment(arguments: ':1}')))
 
-      message = accumulator.to_message(nil)
-      expect(filtered.filter_map(&:content)).to eq(['Hello'])
-      expect(filtered.filter_map { |chunk| chunk.thinking&.text }.join).to eq('internal')
-      expect(message.content).to eq('Hello')
-      expect(message.thinking.text).to eq('internal')
+      expect(emitted.first).to be_a(canonical::Chunk)
+      expect(emitted.first.type).to eq(:tool_call_delta)
+      response = accumulator.to_response(model: 'm')
+      expect(response.tool_calls.first.arguments).to eq('a' => 1)
     end
 
-    it 'does not stream untagged local-model reasoning preambles as content' do
+    it 'tracks usage from usage chunks into the response' do
       accumulator = described_class.new
-      stream = [
-        'The user is just saying "test".',
-        ' Let me respond simply and confirm things are working.',
-        "\n\nHey! Things are working on my end."
-      ]
-
-      filtered = stream.filter_map do |content|
-        chunk = Legion::Extensions::Llm::Chunk.new(role: :assistant, content: content)
-        accumulator.add(chunk)
-        accumulator.filtered_chunk(chunk)
-      end
+      accumulator.add(canonical::Chunk.usage_chunk(
+                        usage: canonical::Usage.build(input_tokens: 7, output_tokens: 3), request_id: 'req-1'
+                      ))
+      response = accumulator.to_response(model: 'm')
 
-      message = accumulator.to_message(nil)
-      expect(filtered.filter_map(&:content)).to eq(['Hey! Things are working on my end.'])
-      expect(filtered.filter_map { |chunk| chunk.thinking&.text }.join)
-        .to eq('The user is just saying "test". Let me respond simply and confirm things are working.')
-      expect(message.content).to eq('Hey! Things are working on my end.')
-      expect(message.thinking.text)
-        .to eq('The user is just saying "test". Let me respond simply and confirm things are working.')
+      expect(response.usage.input_tokens).to eq(7)
+      expect(response.usage.output_tokens).to eq(3)
     end
 
-    it 'releases normal text that starts like a possible reasoning preamble' do
+    it 'keeps the last stop_reason and falls back to the selected model' do
       accumulator = described_class.new
-      stream = [
-        'The user guide covers setup.',
-        "\n\nFollow the install section first."
-      ]
+      accumulator.add(canonical::Chunk.text_delta(delta: 'x', request_id: 'r', stop_reason: :end_turn))
+      response = accumulator.to_response(model: 'selected-model')
 
-      filtered = stream.filter_map do |content|
-        chunk = Legion::Extensions::Llm::Chunk.new(role: :assistant, content: content)
-        accumulator.add(chunk)
-        accumulator.filtered_chunk(chunk)
-      end
+      expect(response.stop_reason).to eq(:end_turn)
+      expect(response.model).to eq('selected-model')
+    end
+  end
 
-      message = accumulator.to_message(nil)
-      expected = "The user guide covers setup.\n\nFollow the install section first."
-      expect(filtered.filter_map(&:content).join).to eq(expected)
-      expect(message.content).to eq(expected)
-      expect(message.thinking).to be_nil
+  describe 'tool-call fragment correlation (wire law: index first, recency fallback)' do
+    it 'routes interleaved parallel fragments by wire index' do
+      accumulator = described_class.new
+      accumulator.add(tool_fragment(id: 'call-0', name: 'a', arguments: '{"x":', index: 0))
+      accumulator.add(tool_fragment(id: 'call-1', name: 'b', arguments: '{"y":', index: 1))
+      accumulator.add(tool_fragment(arguments: '1}', index: 0))
+      accumulator.add(tool_fragment(arguments: '2}', index: 1))
+
+      tool_calls = accumulator.to_response(model: 'm').tool_calls
+      by_name = tool_calls.to_h { |tc| [tc.name, tc] }
+      expect(by_name['a'].arguments).to eq('x' => 1)
+      expect(by_name['b'].arguments).to eq('y' => 2)
     end
 
-    it 'captures stop_reason from a chunk and propagates it to the assembled Message' do
+    it 'falls back to recency when the provider emits no index' do
       accumulator = described_class.new
-      chunk = Legion::Extensions::Llm::Chunk.new(
-        role: :assistant, content: 'partial', model_id: 'm', stop_reason: :max_tokens
-      )
+      accumulator.add(tool_fragment(name: 'only', arguments: '{"a":'))
+      accumulator.add(tool_fragment(arguments: '1}'))
 
-      accumulator.add(chunk)
-      expect(accumulator.stop_reason).to eq(:max_tokens)
+      response = accumulator.to_response(model: 'm')
+      expect(response.tool_calls.size).to eq(1)
+      expect(response.tool_calls.first.arguments).to eq('a' => 1)
+    end
 
-      message = accumulator.to_message(nil)
-      expect(message.stop_reason).to eq(:max_tokens)
+    it 'opens a name-only call only while nothing is in flight; drops fragments with no call' do
+      accumulator = described_class.new
+      # A bare fragment before any opener is dropped (no call to route to).
+      accumulator.add(tool_fragment(arguments: 'null'))
+      accumulator.add(tool_fragment(name: 'first', arguments: '{"a":'))
+      accumulator.add(tool_fragment(arguments: '1}'))
+
+      tool_calls = accumulator.to_response(model: 'm').tool_calls
+      expect(tool_calls.size).to eq(1)
+      expect(tool_calls.first.name).to eq('first')
+      expect(tool_calls.first.arguments).to eq('a' => 1)
     end
 
-    it 'uses the last non-nil stop_reason when multiple chunks carry one' do
+    it 'generates an id when the wire omits one' do
       accumulator = described_class.new
-      accumulator.add(Legion::Extensions::Llm::Chunk.new(
-                        role: :assistant, content: 'hello', model_id: 'm', stop_reason: :end_turn
-                      ))
-      accumulator.add(Legion::Extensions::Llm::Chunk.new(
-                        role: :assistant, content: nil, model_id: 'm', stop_reason: :max_tokens
-                      ))
+      accumulator.add(tool_fragment(name: 'anon', arguments: '{}'))
+      response = accumulator.to_response(model: 'm')
+      expect(response.tool_calls.first.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
 
-      expect(accumulator.stop_reason).to eq(:max_tokens)
-      expect(accumulator.to_message(nil).stop_reason).to eq(:max_tokens)
+    it 'carries the thought signature in the tool call metadata, never dropped' do
+      accumulator = described_class.new
+      accumulator.add(tool_fragment(id: 'c1', name: 'f', arguments: '{}', signature: 'thought-sig'))
+      response = accumulator.to_response(model: 'm')
+      expect(response.tool_calls.first.metadata).to eq(signature: 'thought-sig')
     end
 
-    it 'leaves stop_reason nil when no chunk carries one' do
+    it 'raises a strict parse error for invalid assembled arguments (U2 — no rescue to {})' do
       accumulator = described_class.new
-      accumulator.add(Legion::Extensions::Llm::Chunk.new(role: :assistant, content: 'hi', model_id: 'm'))
+      accumulator.add(tool_fragment(id: 'c1', name: 'f', arguments: '{"broken"'))
 
-      expect(accumulator.stop_reason).to be_nil
-      expect(accumulator.to_message(nil).stop_reason).to be_nil
+      expect { accumulator.to_response(model: 'm') }
+        .to raise_error(ArgumentError, /not valid JSON/)
     end
+  end
 
-    it 'starts a tool call from an opening fragment with id nil but name present' do
+  describe 'think-tag state machine (U1 — shared segment core, cross-chunk buffering)' do
+    it 'splits think tags split across chunk boundaries without leaking' do
       accumulator = described_class.new
-      tool_call = Legion::Extensions::Llm::ToolCall.new(id: nil, name: 'weather', arguments: '')
-      chunk = Legion::Extensions::Llm::Chunk.new(
-        role: :assistant, content: nil, tool_calls: { weather: tool_call }
-      )
+      emitted = []
+      emitted.concat(accumulator.add(text_chunk('<thinking>')))
+      emitted.concat(accumulator.add(text_chunk('internal</thin')))
+      emitted.concat(accumulator.add(text_chunk('king>visible')))
+      response = accumulator.to_response(model: 'm')
+
+      expect(response.text).to eq('visible')
+      expect(response.thinking.content).to eq('internal')
+      # The split tag itself emits no visible text deltas.
+      expect(emitted.map(&:type)).to eq(%i[thinking_delta text_delta])
+    end
 
-      accumulator.add(chunk)
+    it 'emits thinking and text deltas from a tagged stream' do
+      accumulator = described_class.new
+      emitted = []
+      emitted.concat(accumulator.add(text_chunk('<thinking>')))
+      emitted.concat(accumulator.add(text_chunk('reasoning here')))
+      emitted.concat(accumulator.add(text_chunk('</thinking>and text')))
+
+      expect(emitted.map(&:type)).to eq(%i[thinking_delta text_delta])
+      response = accumulator.to_response(model: 'm')
+      expect(response.text).to eq('and text')
+      expect(response.thinking.content).to eq('reasoning here')
+    end
 
-      frag_call = Legion::Extensions::Llm::ToolCall.new(id: nil, name: nil, arguments: '{"city":"SF"}')
-      frag_chunk = Legion::Extensions::Llm::Chunk.new(
-        role: :assistant, content: nil, tool_calls: { fragment: frag_call }
-      )
-      accumulator.add(frag_chunk)
+    it 'treats content before an unmatched close as thinking (never visible)' do
+      accumulator = described_class.new
+      accumulator.add(text_chunk('preface</thinking>'))
+      accumulator.add(text_chunk('visible'))
+      response = accumulator.to_response(model: 'm')
 
-      message = accumulator.to_message(nil)
-      expect(message.tool_calls.size).to eq(1)
-      tc = message.tool_calls.values.first
-      expect(tc.name).to eq('weather')
-      expect(tc.arguments).to eq({ 'city' => 'SF' })
+      expect(response.text).to eq('visible')
+      expect(response.thinking.content).to eq('preface')
     end
-  end
 
-  describe '#filtered_chunk' do
-    it 'returns a chunk for a plain text delta' do
+    it 'keeps a stray open tag siphoning content into thinking until close' do
       accumulator = described_class.new
-      chunk = Legion::Extensions::Llm::Chunk.new(role: :assistant, content: 'Hello', model_id: 'm')
-
-      accumulator.add(chunk)
-      filtered = accumulator.filtered_chunk(chunk)
+      accumulator.add(text_chunk('preamble<thinking>'))
+      accumulator.add(text_chunk('middle'))
+      accumulator.add(text_chunk('</thinking>tail'))
+      response = accumulator.to_response(model: 'm')
 
-      expect(filtered).not_to be_nil
-      expect(filtered.content.to_s).to eq('Hello')
+      expect(response.text).to eq('preambletail')
+      expect(response.thinking.content).to eq('middle')
     end
   end
 
-  describe '#flush_pending_chunk' do
-    it 'returns nil when nothing is buffered' do
+  describe 'untagged-preamble heuristic' do
+    it 'withholds a reasoning-looking preamble until a blank line, then emits it as thinking' do
       accumulator = described_class.new
-      chunk = Legion::Extensions::Llm::Chunk.new(role: :assistant, content: 'Hello', model_id: 'm')
-      accumulator.add(chunk)
-
-      expect(accumulator.flush_pending_chunk).to be_nil
+      emitted = []
+      emitted.concat(accumulator.add(text_chunk("I need to answer this\n")))
+      emitted.concat(accumulator.add(text_chunk("\n\nHere is the answer")))
+
+      response = accumulator.to_response(model: 'm')
+      expect(response.thinking.content).to eq('I need to answer this')
+      expect(response.text).to eq('Here is the answer')
+      expect(emitted.map(&:type).include?(:thinking_delta)).to be(true)
     end
 
-    it 'releases text held by the untagged-preamble heuristic as a final delta' do
+    it 'releases held text as content when the preamble is not reasoning' do
       accumulator = described_class.new
-      deltas = []
-      ['I can help', ' with that.'].each do |text|
-        chunk = Legion::Extensions::Llm::Chunk.new(role: :assistant, content: text, model_id: 'm')
-        accumulator.add(chunk)
-        filtered = accumulator.filtered_chunk(chunk)
-        deltas << filtered.content.to_s if filtered
-      end
+      emitted = []
+      emitted.concat(accumulator.add(text_chunk('Just a normal answer')))
+      expect(emitted.map(&:type)).to eq(%i[text_delta])
+      expect(accumulator.to_response(model: 'm').text).to eq('Just a normal answer')
+    end
 
-      final = accumulator.flush_pending_chunk
-      deltas << final.content.to_s if final
-      message = accumulator.to_message(nil)
+    it 'flushes still-held preamble text at stream end (short responses still stream)' do
+      accumulator = described_class.new
+      accumulator.add(text_chunk("Let me answer\nbriefly"))
+      expect(accumulator.add(text_chunk('more')).map(&:type)).to eq([])
+      emitted = accumulator.flush_pending_chunk
 
-      expect(deltas.join).to eq('I can help with that.')
-      expect(message.content).to eq('I can help with that.')
+      expect(emitted.map(&:type)).to eq(%i[text_delta])
+      expect(accumulator.to_response(model: 'm').text).to eq("Let me answer\nbrieflymore")
     end
+  end
 
-    it 'does not double-append flushed text in to_message' do
+  describe 'response assembly' do
+    it 'assembles a canonical response with usage, thinking, and tool calls' do
       accumulator = described_class.new
-      chunk = Legion::Extensions::Llm::Chunk.new(role: :assistant, content: 'The answer', model_id: 'm')
-      accumulator.add(chunk)
+      accumulator.add(text_chunk('done'))
+      accumulator.add(thinking_chunk('thought', signature: 'sig-9'))
+      accumulator.add(tool_fragment(id: 'c1', name: 'f', arguments: '{"k":"v"}'))
+      accumulator.add(canonical::Chunk.usage_chunk(
+                        usage: canonical::Usage.build(input_tokens: 1, output_tokens: 2), request_id: 'r'
+                      ))
 
-      accumulator.flush_pending_chunk
-      message = accumulator.to_message(nil)
+      response = accumulator.to_response(model: 'm-1')
+      expect(response).to be_a(canonical::Response)
+      expect(response.text).to eq('done')
+      expect(response.thinking.content).to eq('thought')
+      expect(response.thinking.signature).to eq('sig-9')
+      expect(response.tool_calls.first.arguments).to eq('k' => 'v')
+      expect(response.usage.input_tokens).to eq(1)
+    end
 
-      expect(message.content).to eq('The answer')
+    it 'leaves thinking and usage nil when the stream carried none' do
+      response = described_class.new.to_response(model: 'm')
+      expect(response.thinking).to be_nil
+      expect(response.usage).to be_nil
+      expect(response.text).to eq('')
     end
   end
 end

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

@@ -7,6 +7,17 @@ RSpec.describe Legion::Extensions::Llm::Streaming do
     Object.new.tap do |obj|
       obj.extend(described_class)
       obj.define_singleton_method(:build_chunk) { |data| "chunk:#{data['x']}" }
+      # Streaming only ships inside Provider in production; the U8 delegation
+      # passes self to ErrorMiddleware.parse_error, which calls parse_error.
+      obj.define_singleton_method(:parse_error) do |response|
+        body = response.body
+        error = body['error'] if body.is_a?(Hash)
+        if error.is_a?(String)
+          error
+        else
+          (error.is_a?(Hash) ? error['message'] : nil)
+        end
+      end
     end
   end
 
@@ -114,4 +125,20 @@ RSpec.describe Legion::Extensions::Llm::Streaming do
         .to raise_error(Legion::Extensions::Llm::ServerError, /Provider error.*incomplete/)
     end
   end
+
+  describe 'M1 — unparseable error content fails loud (the fail-open is deleted)' do
+    it 'an unparseable error event raises a classified ServerError, never a silent nil' do
+      expect { test_obj.send(:parse_error_from_json, 'not-json{{{', env, 'Failed to parse error chunk') }
+        .to raise_error(Legion::Extensions::Llm::ServerError, /unparseable error event/)
+    end
+
+    it 'an unparseable mid-stream data frame raises a classified ServerError' do
+      expect { test_obj.send(:handle_data, 'not-json{{{', env) }
+        .to raise_error(Legion::Extensions::Llm::ServerError, /unparseable data frame/)
+    end
+
+    it 'an empty data frame is a no-op, not an error' do
+      expect { test_obj.send(:handle_data, '   ', env) }.not_to raise_error
+    end
+  end
 end

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

@@ -16,14 +16,48 @@ RSpec.describe Legion::Extensions::Llm::Taxonomies do
     expect(described_class::TYPES).to include(:inference, :embedding)
   end
 
-  it 'CIRCUIT_STATES contains three states' do
-    expect(described_class::CIRCUIT_STATES).to contain_exactly(:closed, :half_open, :open)
-  end
-
   it 'all constants are frozen' do
     expect(described_class::TIERS).to be_frozen
     expect(described_class::TYPES).to be_frozen
-    expect(described_class::CIRCUIT_STATES).to be_frozen
+    expect(described_class::OPERATIONS).to be_frozen
+    expect(described_class::OPERATION_TO_LANE_TYPE).to be_frozen
+  end
+
+  it 'removes the legacy enums (0.8.0 rip)' do
+    expect(described_class.const_defined?(:CIRCUIT_STATES, false)).to be(false)
+    expect(described_class.const_defined?(:HEALTH_KEYS, false)).to be(false)
+    expect(described_class.const_defined?(:OPERATION_ALIASES, false)).to be(false)
+  end
+
+  describe 'OPERATION_TO_LANE_TYPE (the 5-tuple 4th part)' do
+    it 'maps every canonical operation to a documented lane type' do
+      expect(described_class::OPERATION_TO_LANE_TYPE).to eq(
+        {
+          chat: :inference,
+          stream_chat: :inference,
+          embed: :embedding,
+          image: :image,
+          transcribe: :audio,
+          translate: :audio,
+          speak: :audio,
+          moderate: :inference,
+          count_tokens: :inference
+        }
+      )
+    end
+
+    it 'covers exactly OPERATIONS with values inside TYPES' do
+      expect(described_class::OPERATION_TO_LANE_TYPE.keys.sort).to eq(described_class::OPERATIONS.sort)
+      expect(described_class::OPERATION_TO_LANE_TYPE.values.all? { |value| described_class::TYPES.include?(value) })
+        .to be(true)
+    end
+
+    it 'lane_type_for canonicalizes first and resolves the single table' do
+      expect(described_class.lane_type_for(operation: 'chat')).to eq(:inference)
+      expect(described_class.lane_type_for(operation: :embed)).to eq(:embedding)
+      expect { described_class.lane_type_for(operation: :nope) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+    end
   end
 
   describe 'SSOT v3 enums' do
@@ -53,20 +87,13 @@ RSpec.describe Legion::Extensions::Llm::Taxonomies do
       expect(described_class.normalize_operation(value: :stream_chat)).to eq(:stream_chat)
     end
 
-    it 'accepts only the documented aliases when allow_aliases is true' do
-      {
-        stream: :stream_chat, embedding: :embed, moderation: :moderate,
-        audio_translation: :translate, speech: :speak
-      }.each do |input, canonical|
-        expect(described_class.normalize_operation(value: input, allow_aliases: true)).to eq(canonical)
+    it 'rejects every legacy alias — one canonical spelling (06 P5)' do
+      %i[stream embedding moderation audio_translation speech].each do |input|
+        expect { described_class.normalize_operation(value: input) }
+          .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
       end
     end
 
-    it 'raises on an alias when allow_aliases is false' do
-      expect { described_class.normalize_operation(value: :stream) }
-        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
-    end
-
     it 'raises on unknown, empty, and invalid UTF-8 input' do
       expect { described_class.normalize_operation(value: :nope) }
         .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)

data/spec/legion/extensions/llm/transport/fleet_lane_spec.rb

@@ -17,7 +17,7 @@ RSpec.describe Legion::Extensions::Llm::Transport::FleetLane do
         'x-message-ttl' => 120_000,
         'x-max-length' => 100,
         'x-delivery-limit' => 3,
-        'x-consumer-timeout' => 300_000
+        'x-consumer-timeout' => 90_000
       )
     end
 

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

@@ -3,17 +3,36 @@
 require 'spec_helper'
 
 RSpec.describe Legion::Extensions::Llm::Utils do
-  describe '.hash_get' do
-    it 'fetches a value using a symbol when the hash key is stored as a string' do
-      hash = { 'name' => 'Legion::Extensions::Llm' }
+  describe '.localhost_url?' do
+    it 'detects loopback hosts in URLs and bare host[:port] values' do
+      expect(described_class.localhost_url?('http://localhost:11434/v1')).to be(true)
+      expect(described_class.localhost_url?('http://127.0.0.1:11434/v1')).to be(true)
+      expect(described_class.localhost_url?('http://[::1]:11434/v1')).to be(true)
+      expect(described_class.localhost_url?('localhost:11434')).to be(true)
+      expect(described_class.localhost_url?('127.0.0.1:11434')).to be(true)
+    end
+
+    it 'rejects non-loopback hosts and garbage' do
+      expect(described_class.localhost_url?('http://apollo:11434/v1')).to be(false)
+      expect(described_class.localhost_url?('not a url at all')).to be(false)
+      expect(described_class.localhost_url?('')).to be(false)
+    end
 
-      expect(described_class.hash_get(hash, :name)).to eq('Legion::Extensions::Llm')
+    it 'is the one shared host-locality detector (U15)' do
+      expect(Legion::Extensions::Llm::CredentialSources.localhost?('http://localhost:11434')).to be(true)
+      expect(Legion::Extensions::Llm::CredentialSources.localhost?('http://apollo:11434')).to be(false)
     end
+  end
+
+  describe '.deep_merge (U7 — dup-before-merge policy)' do
+    it 'merges nested hashes without mutating the inputs' do
+      left = { a: { b: 1 }, keep: 1 }
+      right = { a: { c: 2 } }
 
-    it 'fetches a value using a string when the hash key is stored as a symbol' do
-      hash = { name: 'Legion::Extensions::Llm' }
+      merged = described_class.deep_merge(left, right)
 
-      expect(described_class.hash_get(hash, 'name')).to eq('Legion::Extensions::Llm')
+      expect(merged).to eq(a: { b: 1, c: 2 }, keep: 1)
+      expect(left).to eq(a: { b: 1 }, keep: 1)
     end
   end