lex-llm 0.7.3 → 0.8.0

data/spec/legion/extensions/llm/conformance/canonical_type_examples.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# 09 §1 — canonical type conformance: the T-groups as shared examples.
+#
+# The including spec supplies:
+#   let(:type_class)  — the Canonical type
+#   let(:type_source) — a Hash exercising the members (from_hash input)
+#   optionally:
+#     let(:auto_generated_members) — member names filled by the factory when
+#     absent from the source (id, timestamp), excluded from member-equality
+#     checks.
+#
+# Type-specific laws (T4 member survival, T5 enum law, T7 member normalization
+# for the type's normalizable members) are asserted in each type spec.
+
+RSpec.shared_examples 'a canonical type' do
+  let(:type) { type_class }
+  let(:built) { type.from_hash(type_source) }
+
+  describe 'T1 — strict input' do
+    it 'raises a typed ArgumentError on nil (no nil factory)' do
+      expect { type.from_hash(nil) }
+        .to raise_error(ArgumentError, /expected Hash, got NilClass/)
+    end
+
+    it 'raises a typed ArgumentError naming the offending class on wrong-class input' do
+      expect { type.from_hash('not a hash') }
+        .to raise_error(ArgumentError, /expected Hash, got String/)
+      expect { type.from_hash(42) }
+        .to raise_error(ArgumentError, /expected Hash, got Integer/)
+    end
+
+    it 'never returns nil from from_hash (valid instances or typed raises only)' do
+      expect(type.from_hash(type_source)).not_to be_nil
+      result =
+        begin
+          type.from_hash({})
+        rescue ArgumentError
+          :typed_raise
+        end
+      expect(result).not_to be_nil
+    end
+  end
+
+  describe 'T2 — unknown-key policy (04 L5)' do
+    it 'folds unknown keys into metadata verbatim — no drops, no raises' do
+      source = type_source.merge(fleet_unknown_key: 'kept', other_unknown: [1, 2])
+      instance = type.from_hash(source)
+
+      expect(instance.metadata).to include(fleet_unknown_key: 'kept', other_unknown: [1, 2])
+    end
+
+    it 'round-trips the folded unknowns' do
+      source = type_source.merge(fleet_unknown_key: 'kept')
+      instance = type.from_hash(source)
+      expect(type.from_hash(instance.to_h).metadata).to include(fleet_unknown_key: 'kept')
+    end
+  end
+
+  describe 'T3 — round-trip identity (04 L7)' do
+    it 'build → to_h → from_hash → Data-equal' do
+      expect(type.from_hash(built.to_h)).to eq(built)
+    end
+
+    it 'to_h is a plain Hash with symbol keys (no member lost, no key invented)' do
+      hash = built.to_h
+      expect(hash).to be_a(Hash)
+      expect(hash.keys).to all(be_a(Symbol))
+      checkable = (type.members.map(&:to_sym) - auto_generated_members)
+      checkable.each do |member|
+        value = built.public_send(member)
+        next if value.nil?
+
+        expect(hash.key?(member)).to be(true)
+      end
+    end
+  end
+
+  describe 'T6 — serialization uniformity (04 L8)' do
+    it 'as_json == to_h and to_json == to_h.to_json' do
+      expect(built.as_json).to eq(built.to_h)
+      expect(built.to_json).to eq(built.to_h.to_json)
+    end
+  end
+
+  # H1: .new is the single strict constructor — it runs the same member
+  # contract as the factories. Poison that passes an is_a? check is not
+  # constructible through ANY public path.
+  describe 'T8 — strict .new (H1: one validated constructor)' do
+    let(:member_kwargs) { type_source.transform_keys(&:to_sym) }
+
+    it 'rejects unknown members with a typed ArgumentError (no silent drops)' do
+      expect { type_class.new(**member_kwargs, not_a_member: true) }
+        .to raise_error(ArgumentError, /not_a_member/)
+    end
+
+    it 'rejects a non-Hash metadata member' do
+      expect { type_class.new(**member_kwargs, metadata: 'not-a-hash') }
+        .to raise_error(ArgumentError, /metadata expected Hash, got String/)
+    end
+
+    it 'constructs valid data (the factories and .new share one contract)' do
+      expect { type_class.new(**member_kwargs) }.not_to raise_error
+    end
+  end
+end

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

@@ -5,10 +5,17 @@
 # Ship location: spec/legion/extensions/llm/conformance/
 # Module: Canonical::Conformance
 #
-# Consumer pattern (in provider gem spec_helper):
+# Consumer pattern (in provider gem spec_helper) — load the kit's example
+# modules BY EXPLICIT NAME. Do NOT glob the kit dir: it also ships lex-llm's
+# own self-test specs (echo_translator_spec, ssot_*_conformance_spec) plus
+# their support files, which LoadError outside this repo.
 #   kit = File.join(Gem.loaded_specs['lex-llm'].full_gem_path,
 #                   'spec/legion/extensions/llm/conformance')
-#   Dir[File.join(kit, '**', '*.rb')].sort.each { |f| require f }
+#   %w[conformance.rb canonical_type_examples.rb client_translator_examples.rb
+#       provider_translator_examples.rb provider_tool_rendering_examples.rb
+#       ssot_contract_examples.rb ssot_provider_examples.rb].each do |f|
+#     require File.join(kit, f)
+#   end
 #
 # Then in specs:
 #   it_behaves_like 'a canonical provider translator', described_class
@@ -47,5 +54,6 @@ module Canonical
   end
 end
 
+require_relative 'canonical_type_examples'
 require_relative 'provider_translator_examples'
 require_relative 'client_translator_examples'

data/spec/legion/extensions/llm/conformance/provider_translator_examples.rb

@@ -298,7 +298,7 @@ RSpec.shared_examples 'a canonical provider translator' do |translator_class|
       it 'preserves tool call identity across chunks' do
         tool_chunks = chunks.select { |c| c['type'] == 'tool_call_delta' }
         parsed_chunks = tool_chunks.map { |c| translator.parse_chunk(c) }
-        ids = parsed_chunks.map { |c| c.tool_call&.id }
+        ids = parsed_chunks.map { |c| c.tool_call.is_a?(Hash) ? c.tool_call[:id] : c.tool_call&.id }
         expect(ids.uniq.length).to eq(1)
       end
     end

data/spec/legion/extensions/llm/conformance/ssot_contract_conformance_spec.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/registry'
+require 'support/ssot_registry_helpers'
+require_relative 'conformance'
+require_relative 'ssot_contract_examples'
+
+# Kit self-test: the B/F/R shared examples run against a real Provider-derived
+# callable, the real Registry, and the real fleet responder/worker — proving
+# the examples provider gems will load are executable and meaningful.
+# rubocop:disable RSpec/DescribeClass, RSpec/MultipleMemoizedHelpers -- kit host
+RSpec.describe 'SSOT v4 contract conformance kit' do
+  include SsotRegistryHelpers
+
+  let(:registry) { Legion::Extensions::Llm::Inventory::Registry }
+  let(:family) { :fake_llm }
+  let(:key) do
+    Legion::Extensions::Llm::Inventory::Identity::InstanceKey.new(provider_family: family, instance_id: 'primary')
+  end
+  let(:coordinator) { probe_coordinator(key) }
+  let(:activated) { true }
+
+  # A real 0.8.0 callable: Provider-derived, canonical in and out, no HTTP.
+  let(:callable) do
+    Class.new(Legion::Extensions::Llm::Provider) do
+      def self.slug = 'kit'
+      def self.configuration_requirements = []
+      def api_base = 'https://kit.invalid'
+
+      def chat(messages, model:, tools: nil, **_rest)
+        enforce_canonical_messages!(messages)
+        enforce_canonical_tools!(tools)
+        Legion::Extensions::Llm::Canonical::Response.build(text: 'ok', model: model, stop_reason: :end_turn)
+      end
+
+      # rubocop:disable Lint/UnusedMethodArgument -- model: mirrors the 0.8.0 callable contract
+      def stream_chat(messages, model: nil, tools: nil, **_contract, &block)
+        enforce_canonical_messages!(messages)
+        enforce_canonical_tools!(tools)
+        block&.call(Legion::Extensions::Llm::Canonical::Chunk.text_delta(delta: 'ok', request_id: nil))
+        block&.call(Legion::Extensions::Llm::Canonical::Chunk.done(request_id: nil, stop_reason: :end_turn,
+                                                                   usage: Legion::Extensions::Llm::Canonical::Usage.build(input_tokens: 1)))
+        nil
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
+
+      def count_tokens(messages:, **_contract)
+        enforce_canonical_messages!(messages)
+        1
+      end
+    end.new(Legion::Extensions::Llm.config)
+  end
+  let(:instance_key) { key }
+  let(:lane_id) { registry.snapshot.lanes_for(instance_key: key).first.lane_id }
+  # The fleet claim field keeps the name offering_id (D4 protocol continuity);
+  # its value is the lane's 5 tuple.
+  let(:offering_id) { lane_id }
+  let(:callable_handle) { registry.snapshot.instance(instance_key: key).callable_handle }
+  let(:operation_evidence_map) { operation_evidence }
+  let(:unknown_value) do
+    Legion::Extensions::Llm::Inventory::ValueEvidence.new(status: :unknown, source: :absent)
+  end
+  let(:exact_envelope_data) do
+    {
+      request_id: 'req-1', correlation_id: 'corr-1', idempotency_key: 'idem-1',
+      operation: 'chat', provider: family.to_s, provider_instance: 'primary', model: 'gemma4',
+      params: { messages: [{ role: 'user', content: 'hello' }] },
+      reply_to: 'reply.1', message_context: {}, caller: 'e2e', trace_context: {},
+      signed_token: 'unsigned', timeout_seconds: 30,
+      expires_at: (Time.now.utc + 120).iso8601,
+      protocol_version: Legion::Extensions::Llm::Fleet::Protocol::VERSION,
+      execution_contract: Legion::Extensions::Llm::Fleet::Protocol::EXACT_EXECUTION_CONTRACT,
+      offering_id: offering_id
+    }
+  end
+  let(:valid_request_options) do
+    {
+      routing_key: 'llm.fleet.inference.gemma4.ctx8192',
+      request_id: 'req-1', correlation_id: 'corr-1', idempotency_key: 'idem-1',
+      operation: :chat, provider: family.to_s, provider_instance: 'primary', model: 'gemma4',
+      params: { messages: [{ role: 'user', content: 'hello' }] },
+      reply_to: 'reply.1', message_context: {}, caller: 'e2e', trace_context: {},
+      signed_token: 'signed.jwt', timeout_seconds: 30, expires_at: '2026-08-20T12:00:00Z',
+      protocol_version: Legion::Extensions::Llm::Fleet::Protocol::VERSION,
+      execution_contract: Legion::Extensions::Llm::Fleet::Protocol::EXACT_EXECUTION_CONTRACT,
+      offering_id: offering_id
+    }
+  end
+
+  before do
+    registry.reset!
+    claim_and_activate(
+      key: key, callable: callable, coordinator: coordinator, model: 'gemma4',
+      weight_inputs: { tier: 100, provider: 50, instance: 2, model_or_offering: 1 },
+      base_weight: 10_000
+    )
+    allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value).and_call_original
+    allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
+      .with(:fleet, :auth, :require_signed_token, default: true).and_return(false)
+    allow(Legion::Extensions::Llm::Fleet::Settings).to receive(:value)
+      .with(:fleet, :responder, :require_idempotency, default: nil).and_return(false)
+    Legion::Extensions::Llm::Fleet::WorkerExecution.reset_idempotency_cache!
+    Legion::Extensions::Llm::Fleet::TokenValidator.reset_replay_cache!
+  end
+
+  it_behaves_like 'B1 — central canonical enforcement (08 F2)'
+  it_behaves_like 'B1b — central canonical tool enforcement (H3)'
+  it_behaves_like 'B2 — canonical outputs (05 O5, 08 R2)'
+  it_behaves_like 'B3 — operation preservation (PR #189 defect class)'
+  it_behaves_like 'B4 — no model re-derivation (PR #45 law)'
+  it_behaves_like 'B5 — no weight recomputation (PR #47 defect class)'
+  it_behaves_like 'B6 — zero-weight disable (U4)'
+  it_behaves_like 'B7 — health authority (RULES 9)'
+  it_behaves_like 'B8 — exact execution never downgrades (06 P2/W1)'
+  it_behaves_like 'B9 — no silent defaults (06 W5)'
+  it_behaves_like 'F1 — envelope round-trip (06 E2)'
+  it_behaves_like 'F2 — rehydration identity (06 W4, E01)'
+  it_behaves_like 'F3 — signing law (06 S3)'
+  it_behaves_like 'F4 — fencing (07 §3)'
+  it_behaves_like 'F5 — response envelope (06 E3/E4)'
+  it_behaves_like 'F6 — contract errors (06 §5)'
+  it_behaves_like 'F7 — retryability (06 F6)'
+  it_behaves_like 'R1 — state machine (07 §3)'
+  it_behaves_like 'R2 — identity (07 §1, 5-tuple law)'
+  it_behaves_like 'R3 — snapshot law (07 §5)'
+  it_behaves_like 'R4 — weight law (07 §4)'
+  it_behaves_like 'R5 — callable lifecycle (07 §6)'
+end
+# rubocop:enable RSpec/DescribeClass, RSpec/MultipleMemoizedHelpers