lex-llm 0.7.3 → 0.8.0

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

@@ -1,285 +1,99 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../conformance/conformance'
 
 RSpec.describe Legion::Extensions::Llm::Canonical::Chunk do
-  describe '.text_delta' do
-    it 'creates a text delta chunk' do
-      chunk = described_class.text_delta(delta: 'hello', request_id: 'req-1')
-
-      expect(chunk.type).to eq(:text_delta)
-      expect(chunk.delta).to eq('hello')
-      expect(chunk.request_id).to eq('req-1')
-      expect(chunk.index).to eq(0)
-      expect(chunk.timestamp).to be_a(Time)
-    end
-
-    it 'accepts block_index and item_id' do
-      chunk = described_class.text_delta(
-        delta: 'hello',
-        request_id: 'req-1',
-        block_index: 0,
-        item_id: 'item-1'
-      )
-
-      expect(chunk.block_index).to eq(0)
-      expect(chunk.item_id).to eq('item-1')
-    end
-  end
-
-  describe '.thinking_delta' do
-    it 'creates a thinking delta chunk' do
-      chunk = described_class.thinking_delta(
-        delta: 'reasoning',
-        request_id: 'req-1',
-        signature: 'sig-partial'
-      )
-
-      expect(chunk.type).to eq(:thinking_delta)
-      expect(chunk.delta).to eq('reasoning')
-      expect(chunk.signature).to eq('sig-partial')
-    end
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { [:timestamp] }
+  let(:type_source) do
+    {
+      request_id: 'req_1',
+      conversation_id: 'conv_1',
+      exchange_id: 'exch_1',
+      index: 3,
+      type: 'text_delta',
+      delta: 'hello',
+      metadata: { origin: 'provider' }
+    }
   end
 
-  describe '.tool_call_delta' do
-    it 'creates a tool call delta chunk' do
-      tool_call = Legion::Extensions::Llm::Canonical::ToolCall.build(name: 'search')
-      chunk = described_class.tool_call_delta(tool_call: tool_call, request_id: 'req-1')
+  it_behaves_like 'a canonical type'
 
-      expect(chunk.type).to eq(:tool_call_delta)
-      expect(chunk.tool_call).to eq(tool_call)
+  describe 'G20d — produce side strict, consume side lenient' do
+    it 'produces valid CHUNK_TYPES via the named factories' do
+      expect(described_class.text_delta(delta: 'x', request_id: 'r').type).to eq(:text_delta)
+      expect(described_class.thinking_delta(delta: 'x', request_id: 'r').type).to eq(:thinking_delta)
+      expect(described_class.tool_call_delta(tool_call: { id: 'i' }, request_id: 'r').type).to eq(:tool_call_delta)
+      expect(described_class.usage_chunk(usage: Legion::Extensions::Llm::Canonical::Usage.build(input_tokens: 1),
+                                         request_id: 'r').type).to eq(:usage)
+      expect(described_class.done(request_id: 'r').type).to eq(:done)
+      expect(described_class.error_chunk(error: 'boom', request_id: 'r').type).to eq(:error)
     end
-  end
 
-  describe '.usage_chunk' do
-    it 'creates a usage chunk' do
-      usage = Legion::Extensions::Llm::Canonical::Usage.new(
-        input_tokens: 100, output_tokens: 50,
-        cache_read_tokens: nil, cache_write_tokens: nil,
-        thinking_tokens: nil, units: {}
-      )
-      chunk = described_class.usage_chunk(usage: usage, request_id: 'req-1')
-
-      expect(chunk.type).to eq(:usage)
-      expect(chunk.usage).to eq(usage)
+    it 'the generic produce path validates type against CHUNK_TYPES' do
+      expect { described_class.build(type: :bogus, request_id: 'r') }
+        .to raise_error(ArgumentError, /Invalid type: :bogus/)
+      expect(described_class.build(type: 'usage', request_id: 'r').type).to eq(:usage)
     end
-  end
 
-  describe '.done' do
-    it 'creates a done chunk' do
-      chunk = described_class.done(request_id: 'req-1', stop_reason: :end_turn)
-
-      expect(chunk.type).to eq(:done)
-      expect(chunk.stop_reason).to eq(:end_turn)
+    it 'consume passes unknown types through unchanged (ignore-unknown on consume)' do
+      chunk = described_class.from_hash(type: 'weird_custom_type', delta: 'x')
+      expect(chunk.type).to eq(:weird_custom_type)
     end
 
-    it 'includes usage when provided' do
-      usage = Legion::Extensions::Llm::Canonical::Usage.new(
-        input_tokens: 100, output_tokens: 50,
-        cache_read_tokens: nil, cache_write_tokens: nil,
-        thinking_tokens: nil, units: {}
-      )
-      chunk = described_class.done(request_id: 'req-1', usage: usage, stop_reason: :end_turn)
-
-      expect(chunk.usage).to eq(usage)
+    it 'H1: .new validates member shapes (type is String|Symbol, never a Hash)' do
+      expect { described_class.new(type: { not: :a_type }, request_id: 'r') }
+        .to raise_error(ArgumentError, /type expected String or Symbol, got Hash/)
+      expect(described_class.new(type: 'text_delta', request_id: 'r').type).to eq(:text_delta)
     end
   end
 
-  describe '.error_chunk' do
-    it 'creates an error chunk' do
-      chunk = described_class.error_chunk(error: 'timeout', request_id: 'req-1')
-
-      expect(chunk.type).to eq(:error)
-      expect(chunk.stop_reason).to eq(:error)
-      expect(chunk.metadata[:error]).to eq('timeout')
-    end
-
-    it 'merges additional metadata' do
-      chunk = described_class.error_chunk(
-        error: 'timeout',
-        request_id: 'req-1',
-        metadata: { provider: 'anthropic' }
-      )
-
-      expect(chunk.metadata[:error]).to eq('timeout')
-      expect(chunk.metadata[:provider]).to eq('anthropic')
+  describe 'O03a — no finish_reason alias' do
+    it 'does not translate finish_reason (it folds into metadata)' do
+      chunk = described_class.from_hash(type: 'done', stop_reason: nil, finish_reason: 'stop')
+      expect(chunk.stop_reason).to be_nil
+      expect(chunk.metadata).to eq(finish_reason: 'stop')
     end
   end
 
-  describe '.from_hash' do
-    it 'parses from hash with symbol keys' do
-      chunk = described_class.from_hash(
-        type: :text_delta,
-        delta: 'hello',
-        request_id: 'req-1'
-      )
-
-      expect(chunk.type).to eq(:text_delta)
-      expect(chunk.delta).to eq('hello')
-      expect(chunk.request_id).to eq('req-1')
-    end
-
-    it 'normalizes type string to symbol' do
-      chunk = described_class.from_hash(type: 'text_delta', delta: 'hello', request_id: 'req-1')
-
-      expect(chunk.type).to eq(:text_delta)
-    end
-
-    it 'parses nested tool_call' do
-      chunk = described_class.from_hash(
-        type: :tool_call_delta,
-        request_id: 'req-1',
-        tool_call: { name: 'search', arguments: { query: 'test' } }
-      )
-
-      expect(chunk.tool_call).to be_a(Legion::Extensions::Llm::Canonical::ToolCall)
-      expect(chunk.tool_call.name).to eq('search')
-    end
-
-    it 'parses nested usage' do
+  describe 'nested member normalization (L2)' do
+    it 'normalizes Hash usage and tool_call fragments' do
       chunk = described_class.from_hash(
-        type: :usage,
-        request_id: 'req-1',
-        usage: { input_tokens: 100, output_tokens: 50 }
+        type: 'usage',
+        usage: { input_tokens: 5 },
+        tool_call: { id: 'i1', name: 'f', arguments: '{"a"', index: 0 }
       )
-
       expect(chunk.usage).to be_a(Legion::Extensions::Llm::Canonical::Usage)
+      expect(chunk.usage.input_tokens).to eq(5)
+      expect(chunk.tool_call).to eq(id: 'i1', name: 'f', arguments: '{"a"', index: 0)
     end
 
-    it 'normalizes stop_reason' do
-      chunk = described_class.from_hash(
-        type: :done,
-        request_id: 'req-1',
-        stop_reason: 'end_turn'
-      )
-
-      expect(chunk.stop_reason).to eq(:end_turn)
-    end
-
-    it 'accepts finish_reason as alias' do
-      chunk = described_class.from_hash(
-        type: :done,
-        request_id: 'req-1',
-        finish_reason: 'tool_use'
-      )
-
-      expect(chunk.stop_reason).to eq(:tool_use)
-    end
-
-    it 'returns nil for nil source' do
-      expect(described_class.from_hash(nil)).to be_nil
-    end
-
-    it 'handles string keys' do
-      chunk = described_class.from_hash(
-        'type' => 'text_delta',
-        'delta' => 'hello',
-        'request_id' => 'req-1'
-      )
-
-      expect(chunk.type).to eq(:text_delta)
-      expect(chunk.delta).to eq('hello')
+    it 'raises on wrong-class nested members' do
+      expect { described_class.from_hash(type: 'usage', usage: 'nope') }
+        .to raise_error(ArgumentError, /usage expected Hash, got String/)
+      expect { described_class.build(tool_call: 42, type: :tool_call_delta, request_id: 'r') }
+        .to raise_error(ArgumentError, /tool_call expected Hash \| .+ToolCall, got Integer/)
     end
   end
 
-  describe '#to_h' do
-    it 'serializes to compact hash' do
-      chunk = described_class.text_delta(delta: 'hello', request_id: 'req-1')
-      hash = chunk.to_h
-
-      expect(hash).to include(type: :text_delta, delta: 'hello', request_id: 'req-1')
-    end
-
-    it 'serializes nested objects' do
-      tool_call = Legion::Extensions::Llm::Canonical::ToolCall.build(name: 'search')
-      chunk = described_class.tool_call_delta(tool_call: tool_call, request_id: 'req-1')
-      hash = chunk.to_h
-
-      expect(hash[:tool_call]).to be_a(Hash)
-      expect(hash[:tool_call][:name]).to eq('search')
+  describe 'T4 — signature and usage survive the wire' do
+    it 'survives build → to_h → JSON → from_hash' do
+      chunk = described_class.thinking_delta(delta: 'hmm', request_id: 'r', signature: 'sig-9')
+      wire = Legion::JSON.load(Legion::JSON.dump(chunk.to_h))
+      round_tripped = described_class.from_hash(wire)
+      expect(round_tripped.signature).to eq('sig-9')
+      expect(round_tripped.delta).to eq('hmm')
+      expect(round_tripped.type).to eq(:thinking_delta)
     end
   end
 
-  describe 'type predicates' do
-    it 'identifies text_delta chunks' do
-      chunk = described_class.text_delta(delta: 'hello', request_id: 'req-1')
-      expect(chunk.text_delta?).to be true
-      expect(chunk.content?).to be true
-    end
-
-    it 'identifies thinking_delta chunks' do
-      chunk = described_class.thinking_delta(delta: 'reasoning', request_id: 'req-1')
-      expect(chunk.thinking_delta?).to be true
-      expect(chunk.content?).to be true
-    end
-
-    it 'identifies tool_call_delta chunks' do
-      tc = Legion::Extensions::Llm::Canonical::ToolCall.build(name: 'search')
-      chunk = described_class.tool_call_delta(tool_call: tc, request_id: 'req-1')
-      expect(chunk.tool_call_delta?).to be true
-      expect(chunk.content?).to be false
-    end
-
-    it 'identifies usage chunks' do
-      usage = Legion::Extensions::Llm::Canonical::Usage.new(
-        input_tokens: 100, output_tokens: 50,
-        cache_read_tokens: nil, cache_write_tokens: nil,
-        thinking_tokens: nil, units: {}
-      )
-      chunk = described_class.usage_chunk(usage: usage, request_id: 'req-1')
-      expect(chunk.usage?).to be true
-    end
-
-    it 'identifies done chunks' do
-      chunk = described_class.done(request_id: 'req-1')
-      expect(chunk.done?).to be true
-    end
-
-    it 'identifies error chunks' do
-      chunk = described_class.error_chunk(error: 'timeout', request_id: 'req-1')
-      expect(chunk.error?).to be true
-    end
-  end
-
-  describe 'CHUNK_TYPES' do
-    it 'includes all expected chunk types' do
-      expect(described_class::CHUNK_TYPES).to eq(
-        %i[text_delta thinking_delta tool_call_delta usage done error]
-      )
-    end
-  end
-
-  describe 'round-trip' do
-    it 'preserves text_delta through from_hash/to_h' do
-      original = {
-        type: 'text_delta',
-        delta: 'hello',
-        request_id: 'req-1',
-        block_index: 0,
-        item_id: 'item-1'
-      }
-      chunk = described_class.from_hash(original)
-      serialized = chunk.to_h
-
-      expect(serialized[:type]).to eq(:text_delta)
-      expect(serialized[:delta]).to eq('hello')
-      expect(serialized[:block_index]).to eq(0)
-      expect(serialized[:item_id]).to eq('item-1')
-    end
-
-    it 'preserves done chunk through from_hash/to_h' do
-      original = {
-        type: 'done',
-        request_id: 'req-1',
-        stop_reason: 'end_turn',
-        usage: { input_tokens: 100, output_tokens: 50 }
-      }
-      chunk = described_class.from_hash(original)
-      serialized = chunk.to_h
-
-      expect(serialized[:type]).to eq(:done)
-      expect(serialized[:stop_reason]).to eq(:end_turn)
-      expect(serialized[:usage]).to include(input_tokens: 100, output_tokens: 50)
-    end
+  it 'auto-stamps timestamp when absent and exposes the predicates' do
+    chunk = described_class.text_delta(delta: 'x', request_id: 'r')
+    expect(chunk.timestamp).to be_a(Time)
+    expect(chunk.text_delta?).to be(true)
+    expect(chunk.content?).to be(true)
+    expect(described_class.done(request_id: 'r').done?).to be(true)
+    expect(described_class.error_chunk(error: 'e', request_id: 'r').metadata[:error]).to eq('e')
   end
 end

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

@@ -1,225 +1,80 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../conformance/conformance'
 
 RSpec.describe Legion::Extensions::Llm::Canonical::ContentBlock do
-  describe '.text' do
-    it 'creates a text content block' do
-      block = described_class.text('hello world')
-
-      expect(block.type).to eq(:text)
-      expect(block.text).to eq('hello world')
-    end
-
-    it 'accepts cache_control' do
-      block = described_class.text('hello', cache_control: { type: 'ephemeral' })
-
-      expect(block.cache_control).to eq({ type: 'ephemeral' })
-    end
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { [] }
+  let(:type_source) do
+    { type: 'text', text: 'hello block', metadata: { origin: 'provider' } }
   end
 
-  describe '.thinking' do
-    it 'creates a thinking content block' do
-      block = described_class.thinking('reasoning here')
+  it_behaves_like 'a canonical type'
 
-      expect(block.type).to eq(:thinking)
-      expect(block.text).to eq('reasoning here')
+  describe 'O03a — no type aliases' do
+    it 'does not translate output_text/input_text — untranslated dialect types raise (L4/L6)' do
+      expect { described_class.from_hash(type: 'output_text', text: 'x') }
+        .to raise_error(ArgumentError, /Invalid type: :output_text/)
+      expect { described_class.from_hash(type: 'input_text', text: 'x') }
+        .to raise_error(ArgumentError, /Invalid type: :input_text/)
     end
-  end
 
-  describe '.tool_use' do
-    it 'creates a tool_use content block' do
-      block = described_class.tool_use(id: 'toolu-1', name: 'search', input: { query: 'test' })
-
-      expect(block.type).to eq(:tool_use)
-      expect(block.id).to eq('toolu-1')
-      expect(block.name).to eq('search')
-      expect(block.input).to eq({ query: 'test' })
+    it 'raises on an unknown type value (L6)' do
+      expect { described_class.build(type: :bogus) }
+        .to raise_error(ArgumentError, /Invalid type: :bogus/)
     end
   end
 
-  describe '.tool_result' do
-    it 'creates a tool_result content block' do
-      block = described_class.tool_result(tool_use_id: 'toolu-1', content: 'result')
-
-      expect(block.type).to eq(:tool_result)
-      expect(block.tool_use_id).to eq('toolu-1')
-      expect(block.text).to eq('result')
-      expect(block.is_error).to be false
-    end
-
-    it 'marks error results' do
-      block = described_class.tool_result(tool_use_id: 'toolu-1', content: 'error', is_error: true)
-
-      expect(block.is_error).to be true
+  describe 'H1 — .new is as strict as the factories' do
+    it 'rejects an unknown type in .new' do
+      expect { described_class.new(type: :bogus, text: 'x') }
+        .to raise_error(ArgumentError, /Invalid type: :bogus/)
     end
   end
 
-  describe '.image' do
-    it 'creates an image content block with media_type (G20a)' do
-      block = described_class.image(data: 'base64data', media_type: 'image/png')
-
-      expect(block.type).to eq(:image)
-      expect(block.data).to eq('base64data')
-      expect(block.media_type).to eq('image/png')
-      expect(block.source_type).to eq(:base64)
-    end
-
-    it 'accepts custom source_type and detail' do
-      block = described_class.image(data: 'img.png', media_type: 'image/png', source_type: :url, detail: 'high')
-
-      expect(block.source_type).to eq(:url)
-      expect(block.detail).to eq('high')
-    end
-  end
-
-  describe '.from_hash' do
-    it 'parses a content block from hash' do
-      block = described_class.from_hash(type: 'text', text: 'hello')
-
+  describe 'named factories (produce side)' do
+    it 'builds a text block' do
+      block = described_class.text('hi', cache_control: { type: :ephemeral })
       expect(block.type).to eq(:text)
-      expect(block.text).to eq('hello')
-    end
-
-    it 'handles string keys' do
-      block = described_class.from_hash('type' => 'thinking', 'text' => 'reasoning')
-
-      expect(block.type).to eq(:thinking)
-      expect(block.text).to eq('reasoning')
-    end
-
-    it 'returns nil for nil source' do
-      expect(described_class.from_hash(nil)).to be_nil
-    end
-
-    it 'preserves all fields' do
-      hash = {
-        type: 'tool_use',
-        id: 'toolu-1',
-        name: 'search',
-        input: { query: 'test' },
-        cache_control: { type: 'ephemeral' }
-      }
-      block = described_class.from_hash(hash)
-
-      expect(block.type).to eq(:tool_use)
-      expect(block.id).to eq('toolu-1')
-      expect(block.name).to eq('search')
-      expect(block.input).to eq({ query: 'test' })
-      expect(block.cache_control).to eq({ type: 'ephemeral' })
+      expect(block.text).to eq('hi')
+      expect(block.cache_control).to eq(type: :ephemeral)
+    end
+
+    it 'builds thinking / tool_use / tool_result / image blocks' do
+      expect(described_class.thinking('hmm').thinking?).to be(true)
+      use = described_class.tool_use(id: 'tu_1', name: 'f', input: { a: 1 })
+      expect(use.tool_use?).to be(true)
+      expect(use.input).to eq(a: 1)
+      result = described_class.tool_result(tool_use_id: 'tu_1', content: 'ok', is_error: true)
+      expect(result.tool_result?).to be(true)
+      expect(result.is_error).to be(true)
+      image = described_class.image(data: 'AAA=', media_type: 'image/png')
+      expect(image.type).to eq(:image)
+      expect(image.media_type).to eq('image/png')
     end
   end
 
-  describe '#to_h' do
-    it 'serializes to compact hash' do
-      block = described_class.text('hello')
-      hash = block.to_h
-
-      expect(hash).to eq(type: :text, text: 'hello')
-    end
-
-    it 'omits nil values' do
-      block = described_class.new(
-        type: :text, text: 'hello', data: nil, source_type: nil,
-        media_type: nil, detail: nil, name: nil, file_id: nil,
-        id: nil, input: nil, tool_use_id: nil, is_error: nil,
-        source: nil, start_index: nil, end_index: nil,
-        code: nil, message: nil, cache_control: nil
-      )
-      hash = block.to_h
-
-      expect(hash).to eq(type: :text, text: 'hello')
+  describe 'F2 fix — no rescue-and-repair' do
+    it 'raises on non-Hash from_hash input instead of fabricating a text block' do
+      expect { described_class.from_hash('corrupted') }
+        .to raise_error(ArgumentError, /expected Hash, got String/)
+      expect { described_class.from_hash(nil) }
+        .to raise_error(ArgumentError, /expected Hash, got NilClass/)
     end
   end
 
-  describe 'type predicates' do
-    it 'identifies text blocks' do
-      block = described_class.text('hello')
-      expect(block.text?).to be true
-      expect(block.thinking?).to be false
-      expect(block.tool_use?).to be false
-      expect(block.tool_result?).to be false
-    end
-
-    it 'identifies thinking blocks' do
-      block = described_class.thinking('reasoning')
-      expect(block.thinking?).to be true
-      expect(block.text?).to be false
-    end
-
-    it 'identifies tool_use blocks' do
-      block = described_class.tool_use(id: '1', name: 'search', input: {})
-      expect(block.tool_use?).to be true
-    end
-
-    it 'identifies tool_result blocks' do
-      block = described_class.tool_result(tool_use_id: '1', content: 'result')
-      expect(block.tool_result?).to be true
-    end
-  end
-
-  describe 'CONTENT_BLOCK_TYPES' do
-    it 'includes all expected types' do
-      expect(described_class::CONTENT_BLOCK_TYPES).to include(
-        :text, :thinking, :tool_use, :tool_result, :image, :audio, :video
-      )
-    end
-  end
-
-  describe 'Responses API type normalization (output_text/input_text)' do
-    it 'normalizes output_text to :text via from_hash' do
-      block = described_class.from_hash(type: 'output_text', text: 'The seat templates')
-
-      expect(block.type).to eq(:text)
-      expect(block.text).to eq('The seat templates')
-      expect(block.text?).to be true
-    end
-
-    it 'normalizes input_text to :text via from_hash' do
-      block = described_class.from_hash(type: 'input_text', text: 'user message')
-
-      expect(block.type).to eq(:text)
-      expect(block.text?).to be true
-    end
-
-    it 'returns text content from to_s for output_text blocks' do
-      block = described_class.from_hash(type: 'output_text', text: "The seat templates don't")
-
-      expect(block.to_s).to eq("The seat templates don't")
-    end
-
-    it 'does not leak #inspect struct into Array#to_s' do
-      blocks = [described_class.from_hash(type: 'output_text', text: 'hello')]
-
-      expect(blocks.inspect).not_to include('data Legion::Extensions')
-      expect(blocks.inspect).not_to include('source_type=nil')
-    end
-  end
-
-  describe '#to_s' do
-    it 'returns text for text blocks' do
-      expect(described_class.text('hello').to_s).to eq('hello')
-    end
-
-    it 'returns placeholder for tool_use blocks' do
-      block = described_class.tool_use(id: '1', name: 'bash', input: {})
-      expect(block.to_s).to eq('[tool_use:bash]')
-    end
-
-    it 'returns placeholder for image blocks' do
-      block = described_class.image(data: 'x', media_type: 'image/png')
-      expect(block.to_s).to eq('[image]')
+  describe 'T4 — member survival' do
+    it 'survives build → to_h → JSON → from_hash' do
+      block = described_class.image(data: 'AAA=', media_type: 'image/png', source_type: :base64)
+      round_tripped = described_class.from_hash(Legion::JSON.load(Legion::JSON.dump(block.to_h)))
+      expect(round_tripped.data).to eq('AAA=')
+      expect(round_tripped.media_type).to eq('image/png')
     end
   end
 
-  describe 'round-trip' do
-    it 'preserves text block through from_hash/to_h' do
-      original = { type: 'text', text: 'hello world' }
-      block = described_class.from_hash(original)
-      serialized = block.to_h
-
-      expect(serialized[:type]).to eq(:text)
-      expect(serialized[:text]).to eq('hello world')
-    end
+  it 'text? is type == :text only (alias list deleted)' do
+    expect(described_class.text('x').text?).to be(true)
+    expect(described_class.thinking('x').text?).to be(false)
   end
 end