lex-llm 0.7.3 → 0.8.0

data/spec/legion/extensions/llm/canonical/message_spec.rb

@@ -1,250 +1,135 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../conformance/conformance'
 
 RSpec.describe Legion::Extensions::Llm::Canonical::Message do
-  describe '.build' do
-    it 'creates a message with required fields' do
-      msg = described_class.build(role: :user, content: 'hello')
-
-      expect(msg.role).to eq(:user)
-      expect(msg.content).to eq('hello')
-      expect(msg.id).to start_with('msg_')
-      expect(msg.status).to eq(:created)
-      expect(msg.version).to eq(1)
-    end
-
-    it 'accepts all fields' do
-      msg = described_class.build(
-        id: 'msg-1',
-        parent_id: 'msg-0',
-        role: :assistant,
-        content: 'response',
-        tool_calls: [],
-        conversation_id: 'conv-1'
-      )
-
-      expect(msg.id).to eq('msg-1')
-      expect(msg.parent_id).to eq('msg-0')
-      expect(msg.role).to eq(:assistant)
-      expect(msg.conversation_id).to eq('conv-1')
-    end
-
-    it 'normalizes string role to symbol' do
-      msg = described_class.build(role: 'user', content: 'hello')
-
-      expect(msg.role).to eq(:user)
-    end
-
-    it 'rejects invalid roles' do
-      expect do
-        described_class.build(role: :invalid, content: 'hello')
-      end.to raise_error(ArgumentError, /Invalid role/)
-    end
-
-    it 'defaults to user role' do
-      msg = described_class.build(content: 'hello')
-
-      expect(msg.role).to eq(:user)
-    end
-
-    it 'sets timestamp automatically' do
-      msg = described_class.build(content: 'hello')
-
-      expect(msg.timestamp).to be_a(Time)
-    end
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { %i[id timestamp] }
+  let(:type_source) do
+    {
+      id: 'msg_1',
+      role: 'user',
+      content: 'hello there',
+      tool_call_id: 'call_1',
+      conversation_id: 'conv_1',
+      cache_control: { type: 'ephemeral' },
+      metadata: { origin: 'client' }
+    }
   end
 
-  describe '.from_hash' do
-    it 'parses from hash with symbol keys' do
-      msg = described_class.from_hash(role: :user, content: 'hello')
+  it_behaves_like 'a canonical type'
 
-      expect(msg.role).to eq(:user)
-      expect(msg.content).to eq('hello')
+  describe 'H1 — .new is as strict as the factories (the bypass is closed)' do
+    it 'rejects a poison role that would pass every is_a? check' do
+      expect { described_class.new(role: :banana, content: 'x') }
+        .to raise_error(ArgumentError, /Invalid role: :banana/)
     end
 
-    it 'normalizes string role to symbol' do
-      msg = described_class.from_hash(role: 'assistant', content: 'response')
-
-      expect(msg.role).to eq(:assistant)
+    it 'rejects a poison content member' do
+      expect { described_class.new(role: :user, content: :symbol) }
+        .to raise_error(ArgumentError, /content expected String \| ContentBlock \| Array, got Symbol/)
     end
 
-    it 'parses content blocks from array of hashes' do
-      msg = described_class.from_hash(
-        role: :user,
-        content: [{ type: 'text', text: 'hello' }]
-      )
-
-      expect(msg.content).to be_an(Array)
-      expect(msg.content.first).to be_a(Legion::Extensions::Llm::Canonical::ContentBlock)
-      expect(msg.content.first.type).to eq(:text)
+    it 'rejects the legacy Hash tool_calls shape' do
+      expect { described_class.new(role: :assistant, tool_calls: { a: { name: 'x' } }) }
+        .to raise_error(ArgumentError, /tool_calls expected Array, got Hash/)
     end
 
-    it 'parses single content block from hash' do
-      msg = described_class.from_hash(
-        role: :user,
-        content: { type: 'text', text: 'hello' }
-      )
-
-      expect(msg.content).to be_a(Legion::Extensions::Llm::Canonical::ContentBlock)
-    end
-
-    it 'parses tool calls from array of hashes' do
-      msg = described_class.from_hash(
-        role: :assistant,
-        tool_calls: [{ name: 'search', arguments: { query: 'test' } }]
-      )
-
-      expect(msg.tool_calls).to be_an(Array)
-      expect(msg.tool_calls.first).to be_a(Legion::Extensions::Llm::Canonical::ToolCall)
-    end
-
-    it 'handles string keys' do
-      msg = described_class.from_hash('role' => 'user', 'content' => 'hello')
-
-      expect(msg.role).to eq(:user)
-      expect(msg.content).to eq('hello')
-    end
-
-    it 'drops the transport-only :cache_control key instead of raising ArgumentError' do
-      # Regression guard (root cause B): the prompt-cache step injects :cache_control
-      # onto every >=2-message request. from_hash previously did build(**h) with the
-      # whole hash, raising ArgumentError 'unknown keyword: :cache_control' before HTTP.
-      # It now projects onto the known member keys, so the transport-only key is dropped.
-      expect do
-        described_class.from_hash(
-          role: 'user',
-          content: 'hi',
-          cache_control: { type: 'ephemeral' }
-        )
-      end.not_to raise_error
-
-      msg = described_class.from_hash(
-        role: 'user',
-        content: 'hi',
-        cache_control: { type: 'ephemeral' }
-      )
-
-      expect(msg).to be_a(described_class)
-      expect(msg.role).to eq(:user)
-      expect(msg.text).to eq('hi')
-    end
-
-    it 'returns nil for nil source' do
-      expect(described_class.from_hash(nil)).to be_nil
+    it 'still constructs valid data (consumer .new calls keep working)' do
+      expect(described_class.new(role: :assistant, content: 'ok')).to be_a(described_class)
     end
   end
 
-  describe '.wrap' do
-    it 'passes through existing Message instances' do
-      msg = described_class.build(role: :user, content: 'hello')
-      wrapped = described_class.wrap(msg)
-
-      expect(wrapped).to eq(msg)
+  describe 'T5 — role enum (validated in both factories)' do
+    it 'accepts the four roles as symbols or strings' do
+      described_class::ROLES.each do |role|
+        expect(described_class.build(role:).role).to eq(role)
+        expect(described_class.from_hash(role: role.to_s).role).to eq(role)
+      end
     end
 
-    it 'parses Hash input' do
-      wrapped = described_class.wrap({ role: :user, content: 'hello' })
-
-      expect(wrapped).to be_a(described_class)
-      expect(wrapped.content).to eq('hello')
-    end
-
-    it 'returns nil for unsupported input' do
-      expect(described_class.wrap('hello')).to be_nil
+    it 'raises on an unknown role in both factories' do
+      expect { described_class.build(role: :bogus) }
+        .to raise_error(ArgumentError, /Invalid role: :bogus/)
+      expect { described_class.from_hash(role: 'bogus') }
+        .to raise_error(ArgumentError, /Invalid role: :bogus/)
     end
   end
 
-  describe '#text' do
-    it 'returns content when it is a String' do
-      msg = described_class.build(role: :user, content: 'hello')
-
-      expect(msg.text).to eq('hello')
+  describe 'L2 — one content/tool_calls normalizer shared by build and from_hash' do
+    it 'normalizes raw-Hash tool_calls to Array<ToolCall> in both factories (T7)' do
+      raw = [{ id: 'tc_1', name: 'get_weather', arguments: { location: 'sf' } }]
+      via_build = described_class.build(role: :assistant, tool_calls: raw)
+      via_hash = described_class.from_hash(role: 'assistant', tool_calls: raw)
+      expect(via_build.tool_calls).to eq(via_hash.tool_calls)
+      expect(via_build.tool_calls).to all(be_a(Legion::Extensions::Llm::Canonical::ToolCall))
+      expect(via_build.tool_calls.first.name).to eq('get_weather')
     end
 
-    it 'extracts text from ContentBlock array' do
-      blocks = [
-        Legion::Extensions::Llm::Canonical::ContentBlock.text('hello'),
-        Legion::Extensions::Llm::Canonical::ContentBlock.text(' world')
-      ]
-      msg = described_class.build(role: :user, content: blocks)
-
-      expect(msg.text).to eq('hello world')
+    it 'normalizes content block hashes in both factories' do
+      via_build = described_class.build(role: :user, content: [{ type: 'text', text: 'hi' }])
+      via_hash = described_class.from_hash(role: 'user', content: [{ type: 'text', text: 'hi' }])
+      expect(via_build.content).to eq(via_hash.content)
+      expect(via_build.content.first).to be_a(Legion::Extensions::Llm::Canonical::ContentBlock)
     end
 
-    it 'skips non-text blocks' do
-      blocks = [
-        Legion::Extensions::Llm::Canonical::ContentBlock.text('hello'),
-        Legion::Extensions::Llm::Canonical::ContentBlock.thinking('reasoning')
-      ]
-      msg = described_class.build(role: :user, content: blocks)
-
-      expect(msg.text).to eq('hello')
+    it 'raises on wrong-class content (the build-accepts-anything gap is closed)' do
+      expect { described_class.build(content: 42) }
+        .to raise_error(ArgumentError, /content expected String \| ContentBlock \| Array, got Integer/)
+      expect { described_class.from_hash(content: 42) }
+        .to raise_error(ArgumentError, /content expected String \| ContentBlock \| Array, got Integer/)
     end
 
-    it 'returns empty string for nil content' do
-      msg = described_class.build(role: :user, content: nil)
-
-      expect(msg.text).to eq('')
+    it 'rejects the legacy Hash tool_calls shape (Array is canonical)' do
+      expect { described_class.build(tool_calls: { a: { name: 'x' } }) }
+        .to raise_error(ArgumentError, /tool_calls expected Array, got Hash/)
     end
+  end
 
-    it 'extracts text from output_text ContentBlock array (Responses API / Codex)' do
-      msg = described_class.from_hash(
-        role: :assistant,
-        content: [{ type: 'output_text', text: "The seat templates don't" }]
-      )
-
-      expect(msg.text).to eq("The seat templates don't")
-      expect(msg.text).not_to include('#<data')
-      expect(msg.text).not_to include('ContentBlock')
+  describe 'E01 — cache_control survives the full round-trip' do
+    it 'survives build → to_h → JSON → from_hash (the fleet-wire variant)' do
+      message = described_class.build(role: :user, content: 'hi', cache_control: { type: 'ephemeral' })
+      wire = Legion::JSON.load(Legion::JSON.dump(message.to_h))
+      expect(wire).to include(cache_control: { type: 'ephemeral' })
+      expect(described_class.from_hash(wire).cache_control).to eq(type: 'ephemeral')
     end
 
-    it 'extracts text from mixed output_text and text blocks' do
-      msg = described_class.from_hash(
-        role: :assistant,
-        content: [
-          { type: 'output_text', text: 'first ' },
-          { type: 'text', text: 'second' }
-        ]
-      )
-
-      expect(msg.text).to eq('first second')
+    it 'is carried by to_h (no projection drop)' do
+      message = described_class.build(role: :user, content: 'hi', cache_control: { type: 'ephemeral' })
+      expect(message.to_h).to include(cache_control: { type: 'ephemeral' })
     end
   end
 
-  describe '#to_h' do
-    it 'serializes to compact hash' do
-      msg = described_class.build(role: :user, content: 'hello')
-      hash = msg.to_h
-
-      expect(hash).to include(id: msg.id, role: :user, content: 'hello')
+  describe 'F1 fix — unknown keys fold into metadata (never dropped)' do
+    it 'folds unknowns on from_hash' do
+      message = described_class.from_hash(role: 'user', content: 'hi', fleet_wire_key: 'kept')
+      expect(message.metadata).to eq(fleet_wire_key: 'kept')
     end
   end
 
-  describe '#to_provider_hash' do
-    it 'returns minimal provider-facing hash' do
-      msg = described_class.build(role: :user, content: 'hello')
-      hash = msg.to_provider_hash
-
-      expect(hash).to eq(role: 'user', content: 'hello')
+  describe 'F2 fix — wrap and to_provider_hash are deleted' do
+    it 'exposes no wrap factory' do
+      expect(described_class.respond_to?(:wrap)).to be(false)
     end
-  end
 
-  describe 'ROLES' do
-    it 'includes all expected roles' do
-      expect(described_class::ROLES).to eq(%i[system user assistant tool])
+    it 'exposes no to_provider_hash projection (L9)' do
+      expect(described_class.build(role: :user, content: 'x')).not_to respond_to(:to_provider_hash)
     end
   end
 
-  describe 'round-trip' do
-    it 'preserves values through from_hash/to_h' do
-      original = { role: 'user', content: 'hello', conversation_id: 'conv-1' }
-      msg = described_class.from_hash(original)
-      serialized = msg.to_h
+  it 'auto-generates msg_<24-hex> ids and timestamps when absent' do
+    message = described_class.build(role: :user, content: 'x')
+    expect(message.id).to match(/\Amsg_[0-9a-f]{24}\z/)
+    expect(message.timestamp).to be_a(Time)
+  end
 
-      expect(serialized[:role]).to eq(:user)
-      expect(serialized[:content]).to eq('hello')
-      expect(serialized[:conversation_id]).to eq('conv-1')
-    end
+  it 'extracts plain text from String and ContentBlock content' do
+    expect(described_class.build(role: :user, content: 'plain').text).to eq('plain')
+    blocks = [
+      Legion::Extensions::Llm::Canonical::ContentBlock.text('a '),
+      Legion::Extensions::Llm::Canonical::ContentBlock.thinking('hidden')
+    ]
+    expect(described_class.build(role: :user, content: blocks).text).to eq('a ')
   end
 end

data/spec/legion/extensions/llm/canonical/params_spec.rb

@@ -1,159 +1,80 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../conformance/conformance'
 
 RSpec.describe Legion::Extensions::Llm::Canonical::Params do
-  describe '.from_hash' do
-    it 'returns a Params instance with canonical fields' do
-      params = described_class.from_hash(max_tokens: 4096, temperature: 0.7)
-
-      expect(params).to be_a(described_class)
-      expect(params.max_tokens).to eq(4096)
-      expect(params.temperature).to eq(0.7)
-      expect(params.top_p).to be_nil
-    end
-
-    it 'normalizes max_output_tokens to max_tokens' do
-      params = described_class.from_hash(max_output_tokens: 2048)
-
-      expect(params.max_tokens).to eq(2048)
-    end
-
-    it 'normalizes num_predict to max_tokens' do
-      params = described_class.from_hash(num_predict: 1024)
-
-      expect(params.max_tokens).to eq(1024)
-    end
-
-    it 'normalizes budget_tokens to max_thinking_tokens' do
-      params = described_class.from_hash(budget_tokens: 5000)
-
-      expect(params.max_thinking_tokens).to eq(5000)
-    end
-
-    it 'normalizes thinking_budget to max_thinking_tokens' do
-      params = described_class.from_hash(thinking_budget: 8000)
-
-      expect(params.max_thinking_tokens).to eq(8000)
-    end
-
-    it 'normalizes stop to stop_sequences' do
-      params = described_class.from_hash(stop: ['\n', 'END'])
-
-      expect(params.stop_sequences).to eq(['\n', 'END'])
-    end
-
-    it 'handles string keys' do
-      params = described_class.from_hash('max_tokens' => '4096', 'temperature' => '0.5')
-
-      expect(params.max_tokens).to eq('4096')
-      expect(params.temperature).to eq('0.5')
-    end
-
-    it 'returns nil for nil source' do
-      expect(described_class.from_hash(nil)).to be_nil
-    end
-
-    it 'returns nil for empty hash' do
-      expect(described_class.from_hash({})).to be_nil
-    end
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { [] }
+  let(:type_source) do
+    {
+      max_tokens: 1024,
+      max_thinking_tokens: 512,
+      temperature: 0.7,
+      top_p: 0.9,
+      top_k: 40,
+      stop_sequences: ['\n\n'],
+      seed: 42,
+      frequency_penalty: 0.1,
+      presence_penalty: 0.2,
+      response_format: { type: 'json_object' },
+      metadata: { source: 'client' }
+    }
+  end
 
-    it 'returns nil when no known keys present' do
-      result = described_class.from_hash(unknown_key: 'value')
+  it_behaves_like 'a canonical type'
 
-      expect(result).to be_nil
+  describe 'O03a — canonical keys only' do
+    it 'does not translate provider spellings (they fold into metadata)' do
+      params = described_class.from_hash(max_output_tokens: 999, num_predict: 888, stop: ['x'])
+      expect(params.max_tokens).to be_nil
+      expect(params.max_thinking_tokens).to be_nil
+      expect(params.stop_sequences).to be_nil
+      expect(params.metadata).to eq(max_output_tokens: 999, num_predict: 888, stop: ['x'])
     end
+  end
 
-    it 'filters unknown keys' do
-      params = described_class.from_hash(
-        max_tokens: 4096,
-        temperature: 0.7,
-        unknown_param: 'should_be_filtered',
-        another_unknown: 123
-      )
-
-      expect(params.max_tokens).to eq(4096)
-      expect(params.temperature).to eq(0.7)
+  describe 'H1/M3 — wire-type validation in every constructor' do
+    it 'rejects garbage numeric members in build, from_hash, and .new' do
+      expect { described_class.build(max_tokens: 'abc') }
+        .to raise_error(ArgumentError, /max_tokens expected Integer, got String/)
+      expect { described_class.from_hash(temperature: :hot) }
+        .to raise_error(ArgumentError, /temperature expected Numeric, got Symbol/)
+      expect { described_class.new(seed: -3.5) }
+        .to raise_error(ArgumentError, /seed expected Integer, got Float/)
     end
 
-    it 'accepts all G18 standard params' do
-      params = described_class.from_hash(
-        max_tokens: 4096,
-        max_thinking_tokens: 10_000,
-        temperature: 0.7,
-        top_p: 0.95,
-        top_k: 50,
-        stop_sequences: ['END'],
-        seed: 42,
-        frequency_penalty: 0.5,
-        presence_penalty: 0.1,
-        response_format: { type: 'json_object' }
-      )
-
-      expect(params.max_tokens).to eq(4096)
-      expect(params.max_thinking_tokens).to eq(10_000)
-      expect(params.temperature).to eq(0.7)
-      expect(params.top_p).to eq(0.95)
-      expect(params.top_k).to eq(50)
-      expect(params.stop_sequences).to eq(['END'])
-      expect(params.seed).to eq(42)
-      expect(params.frequency_penalty).to eq(0.5)
-      expect(params.presence_penalty).to eq(0.1)
-      expect(params.response_format).to eq({ type: 'json_object' })
+    it 'rejects wrong-class stop_sequences and response_format' do
+      expect { described_class.new(stop_sequences: 42) }
+        .to raise_error(ArgumentError, /stop_sequences expected String \| Array, got Integer/)
+      expect { described_class.build(response_format: 42) }
+        .to raise_error(ArgumentError, /response_format expected String \| Hash, got Integer/)
     end
   end
 
-  describe '#to_h' do
-    it 'serializes to compact hash' do
-      params = described_class.new(
-        max_tokens: 4096, temperature: 0.7,
-        max_thinking_tokens: nil, top_p: nil, top_k: nil,
-        stop_sequences: nil, seed: nil,
-        frequency_penalty: nil, presence_penalty: nil,
-        response_format: nil
-      )
-      hash = params.to_h
-
-      expect(hash).to eq(max_tokens: 4096, temperature: 0.7)
+  describe 'construction law' do
+    it 'from_hash({}) is a valid all-nil Params (never nil)' do
+      params = described_class.from_hash({})
+      expect(params).to be_a(described_class)
+      expect(params.max_tokens).to be_nil
+      expect(params.temperature).to be_nil
     end
 
-    it 'includes all non-nil fields' do
-      params = described_class.new(
-        max_tokens: 4096, max_thinking_tokens: 10_000,
-        temperature: 0.7, top_p: 0.95, top_k: 50,
-        stop_sequences: ['END'], seed: 42,
-        frequency_penalty: 0.5, presence_penalty: 0.1,
-        response_format: { type: 'json_object' }
-      )
-      hash = params.to_h
-
-      expect(hash).to include(
-        max_tokens: 4096, max_thinking_tokens: 10_000,
-        temperature: 0.7, top_p: 0.95, top_k: 50,
-        stop_sequences: ['END'], seed: 42,
-        frequency_penalty: 0.5, presence_penalty: 0.1,
-        response_format: { type: 'json_object' }
-      )
+    it 'builds from keyword args' do
+      params = described_class.build(temperature: 1.0)
+      expect(params.temperature).to eq(1.0)
     end
-  end
 
-  describe 'round-trip' do
-    it 'preserves values through from_hash/to_h' do
-      original = { max_tokens: 4096, temperature: 0.7, top_p: 0.95 }
-      params = described_class.from_hash(original)
-      serialized = params.to_h
-
-      expect(serialized).to eq(original)
+    it 'build and from_hash share one normalization path (T7)' do
+      via_build = described_class.build(temperature: 0.5, metadata: { a: 1 })
+      via_hash = described_class.from_hash(temperature: 0.5, metadata: { a: 1 })
+      expect(via_build).to eq(via_hash)
     end
 
-    it 'normalizes provider keys through round-trip' do
-      original = { max_output_tokens: 2048, budget_tokens: 5000, stop: ['END'] }
-      params = described_class.from_hash(original)
-      serialized = params.to_h
-
-      expect(serialized[:max_tokens]).to eq(2048)
-      expect(serialized[:max_thinking_tokens]).to eq(5000)
-      expect(serialized[:stop_sequences]).to eq(['END'])
+    it 'survives build → to_h → JSON → from_hash (T4)' do
+      params = described_class.build(temperature: 0.5, stop_sequences: ['stop'])
+      round_tripped = described_class.from_hash(Legion::JSON.load(Legion::JSON.dump(params.to_h)))
+      expect(round_tripped).to eq(params)
     end
   end
 end