lex-llm 0.7.6 → 0.8.4

data/lib/legion/extensions/llm/canonical/content_block.rb

@@ -1,108 +1,87 @@
 # frozen_string_literal: true
 
+# rubocop:disable-next Metrics/ParameterLists -- factory methods have many params
 module Legion
   module Extensions
     module Llm
       module Canonical
         # Typed content block with media_type support per G20a.
-        # Ports field vocabulary from Legion::LLM::Types::ContentBlock.
-        # rubocop:disable Lint/ConstantDefinitionInBlock -- required for Data.define block scope
+        # Ports field vocabulary from Legion::LLM::Types::ContentBlock. # -- required for Data.define block scope
         ContentBlock = ::Data.define(
           :type, :text, :data, :source_type, :media_type,
           :detail, :name, :file_id,
           :id, :input, :tool_use_id, :is_error,
           :source, :start_index, :end_index,
-          :code, :message, :cache_control
+          :code, :message, :cache_control, :metadata
         ) do
-          TEXT_TYPE_ALIASES = %i[text output_text input_text].freeze
+          # Build from keyword args (primary constructor).
+          def self.build(
+            type: nil, text: nil, 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, metadata: {}
+          )
+            new(
+              type: normalize_type!(type, self::BUILD_SITE),
+              text:, data:, source_type:, media_type:,
+              detail:, name:, file_id:,
+              id:, input:, tool_use_id:, is_error:,
+              source:, start_index:, end_index:,
+              code:, message:, cache_control:,
+              metadata: Strict.metadata!(metadata, self::BUILD_SITE)
+            )
+          end
+
+          # Build from a Hash (raw provider response or deserialized wire payload).
+          # Canonical keys only (O03a); unknown keys fold into metadata (L5).
+          def self.from_hash(source)
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(
+              type: hash[:type], text: hash[:text], data: hash[:data],
+              source_type: hash[:source_type], media_type: hash[:media_type],
+              detail: hash[:detail], name: hash[:name], file_id: hash[:file_id],
+              id: hash[:id], input: hash[:input], tool_use_id: hash[:tool_use_id],
+              is_error: hash[:is_error], source: hash[:source],
+              start_index: hash[:start_index], end_index: hash[:end_index],
+              code: hash[:code], message: hash[:message],
+              cache_control: hash[:cache_control], metadata:
+            )
+          end
+
+          # L6: validate against the declared block types when present.
+          def self.normalize_type!(type, site)
+            return nil if type.nil?
+
+            type_sym = type.is_a?(::String) ? type.to_sym : type
+            Strict.enum!(type_sym, self::CONTENT_BLOCK_TYPES, site, :type)
+          end
 
           # Build a text content block.
           def self.text(content, cache_control: nil)
-            new(
-              type: :text, text: content, 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: cache_control
-            )
+            build(type: :text, text: content, cache_control:)
           end
 
           # Build a thinking content block.
           def self.thinking(content)
-            new(
-              type: :thinking, text: content, 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
-            )
+            build(type: :thinking, text: content)
           end
 
           # Build a tool_use content block.
           def self.tool_use(id:, name:, input:)
-            new(
-              type: :tool_use, text: nil, data: nil, source_type: nil, media_type: nil,
-              detail: nil, name: name, file_id: nil, id: id, input: input,
-              tool_use_id: nil, is_error: nil, source: nil, start_index: nil,
-              end_index: nil, code: nil, message: nil, cache_control: nil
-            )
+            build(type: :tool_use, id:, name:, input:)
           end
 
           # Build a tool_result content block.
           def self.tool_result(tool_use_id:, content:, is_error: false)
-            new(
-              type: :tool_result, text: content, data: nil, source_type: nil, media_type: nil,
-              detail: nil, name: nil, file_id: nil, id: nil, input: nil,
-              tool_use_id: tool_use_id, is_error: is_error, source: nil, start_index: nil,
-              end_index: nil, code: nil, message: nil, cache_control: nil
-            )
+            build(type: :tool_result, text: content, tool_use_id:, is_error:)
           end
 
           # Build an image content block with media_type (G20a).
           def self.image(data:, media_type:, source_type: :base64, detail: nil)
-            new(
-              type: :image, text: nil, data: data, source_type: source_type, media_type: media_type,
-              detail: detail, 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
-            )
-          end
-
-          # Build from a Hash (raw provider response or deserialized wire payload).
-          # Rescues NoMethodError from corrupted inputs (e.g. String elements from
-          # prior serialization bugs where ContentBlock#inspect leaked into storage).
-          def self.from_hash(source)
-            return nil if source.nil?
-
-            h = source.transform_keys(&:to_sym)
-            type_raw = h.delete(:type)
-            if type_raw
-              type_sym = type_raw.to_sym
-              h[:type] = TEXT_TYPE_ALIASES.include?(type_sym) ? :text : type_sym
-            end
-
-            new(
-              type: h[:type],
-              text: h[:text],
-              data: h[:data],
-              source_type: h[:source_type],
-              media_type: h[:media_type],
-              detail: h[:detail],
-              name: h[:name],
-              file_id: h[:file_id],
-              id: h[:id],
-              input: h[:input],
-              tool_use_id: h[:tool_use_id],
-              is_error: h[:is_error],
-              source: h[:source],
-              start_index: h[:start_index],
-              end_index: h[:end_index],
-              code: h[:code],
-              message: h[:message],
-              cache_control: h[:cache_control]
-            )
-          rescue NoMethodError => e
-            Legion::Logging.log.warn('[canonical][content_block] from_hash received non-Hash input ' \
-                                     "(#{source.class}): #{e.message}")
-            text(source.to_s)
+            build(type: :image, data:, media_type:, source_type:, detail:)
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
@@ -134,7 +113,7 @@ module Legion
 
           # Whether this block carries textual content.
           def text?
-            TEXT_TYPE_ALIASES.include?(type)
+            type == :text
           end
 
           # Whether this block carries thinking/reasoning content.
@@ -151,10 +130,21 @@ module Legion
           def tool_result?
             type == :tool_result
           end
+
+          # H1: the single strict constructor — .new runs the same member
+          # contract as the factories; the factories fill their defaults and
+          # delegate here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:type] = normalize_type!(values[:type], site)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
         end
 
         ContentBlock::CONTENT_BLOCK_TYPES = %i[text thinking tool_use tool_result image audio video].freeze
-        # rubocop:enable Lint/ConstantDefinitionInBlock
+        ContentBlock::BUILD_SITE = 'Canonical::ContentBlock.build'
+        ContentBlock::FROM_HASH_SITE = 'Canonical::ContentBlock.from_hash'
+        ContentBlock::NEW_SITE = 'Canonical::ContentBlock.new'
       end
     end
   end

data/lib/legion/extensions/llm/canonical/message.rb

@@ -2,41 +2,37 @@
 
 require 'securerandom'
 
-# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+# rubocop:disable-next Metrics/ParameterLists -- factory methods have many params
 module Legion
   module Extensions
     module Llm
+      # -- required for Data.define block scope
       module Canonical
-        # rubocop:disable Lint/ConstantDefinitionInBlock -- required for Data.define block scope
         # Canonical message in a conversation.
-        # Ports field vocabulary from Legion::LLM::Types::Message and lex-llm Message.
+        # Ports field vocabulary from Legion::LLM::Types::Message.
+        # Unknown keys fold into the metadata member (04 L5) — never dropped.
+        # :cache_control (prompt-cache breakpoints) IS a member and survives
+        # build/to_h/JSON round-trips, including the fleet wire.
         Message = ::Data.define(
           :id, :parent_id, :role, :content, :tool_calls, :tool_call_id,
           :name, :status, :version, :timestamp, :seq,
           :provider, :model, :input_tokens, :output_tokens,
-          :conversation_id, :task_id
+          :conversation_id, :task_id, :cache_control, :metadata
         ) do
-          ROLES = %i[system user assistant tool].freeze
-
           # Build from keyword args (primary constructor).
           def self.build(
             id: nil, parent_id: nil, role: :user, content: nil, tool_calls: nil,
             tool_call_id: nil, name: nil, status: :created, version: 1,
             timestamp: nil, seq: nil, provider: nil, model: nil,
-            input_tokens: nil, output_tokens: nil, conversation_id: nil, task_id: nil
+            input_tokens: nil, output_tokens: nil, conversation_id: nil, task_id: nil,
+            cache_control: nil, metadata: {}
           )
-            role_sym = role.is_a?(String) ? role.to_sym : role
-            unless ROLES.include?(role_sym)
-              raise ArgumentError,
-                    "Invalid role: #{role_sym}. Must be one of: #{ROLES.join(', ')}"
-            end
-
             new(
               id: id || "msg_#{SecureRandom.hex(12)}",
               parent_id: parent_id,
-              role: role_sym,
-              content: content,
-              tool_calls: tool_calls,
+              role: normalize_role!(role, self::BUILD_SITE),
+              content: normalize_content!(content, self::BUILD_SITE),
+              tool_calls: normalize_tool_calls!(tool_calls, self::BUILD_SITE),
               tool_call_id: tool_call_id,
               name: name,
               status: status,
@@ -48,64 +44,43 @@ module Legion
               input_tokens: input_tokens,
               output_tokens: output_tokens,
               conversation_id: conversation_id,
-              task_id: task_id
+              task_id: task_id,
+              cache_control: cache_control.nil? ? nil : Strict.expect_type!(cache_control, [::Hash], self::BUILD_SITE, :cache_control),
+              metadata: Strict.metadata!(metadata, self::BUILD_SITE)
             )
           end
 
           # Build from a Hash (raw provider response or deserialized wire payload).
-          def self.from_hash(hash)
-            return nil if hash.nil?
-
-            h = hash.transform_keys(&:to_sym)
-
-            # Normalize role to symbol
-            role_raw = h[:role]
-            h[:role] = role_raw&.to_sym if role_raw
-
-            # Parse content blocks if they're an array of hashes
-            content = h[:content]
-            if content.is_a?(Array)
-              h[:content] = content.map do |block|
-                block.is_a?(ContentBlock) ? block : ContentBlock.from_hash(block)
-              end
-            elsif content.is_a?(Hash)
-              h[:content] = ContentBlock.from_hash(content)
-            end
-
-            # Parse tool calls — Array is canonical; Hash is legacy lex-llm format (name → ToolCall)
-            tool_calls = h[:tool_calls]
-            if tool_calls.is_a?(Hash)
-              h[:tool_calls] = tool_calls.values.map do |tc|
-                next tc if tc.is_a?(ToolCall)
+          def self.from_hash(source)
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(**hash, metadata:)
+          end
 
-                raw = tc.respond_to?(:to_h) ? tc.to_h : tc
-                ToolCall.from_hash(raw)
-              end
-            elsif tool_calls.is_a?(Array)
-              h[:tool_calls] = tool_calls.map do |tc|
-                next tc if tc.is_a?(ToolCall)
+          # L6: role validated at construction, in both factories.
+          def self.normalize_role!(role, site)
+            role_sym = role.is_a?(::String) ? role.to_sym : role
+            Strict.enum!(role_sym, self::ROLES, site, :role)
+          end
 
-                if tc.is_a?(Hash)
-                  ToolCall.from_hash(tc)
-                else
-                  ToolCall.from_hash(tc.respond_to?(:to_h) ? tc.to_h : tc)
-                end
-              end
-            end
+          # L2: one content normalizer shared by build and from_hash.
+          # String | ContentBlock | Array<ContentBlock> | nil — anything else raises.
+          def self.normalize_content!(content, site)
+            return nil if content.nil?
+            return content if content.is_a?(::String) || content.is_a?(ContentBlock)
+            raise ArgumentError, "#{site}: content expected String | ContentBlock | Array, got #{content.class}" unless content.is_a?(::Array)
 
-            # Tolerate transport-only keys (e.g. the prompt-cache step's :cache_control,
-            # injected onto every >=2-message request) by projecting onto the known
-            # member set — mirrors Canonical::Request.from_hash, which folds unknown keys
-            # instead of raising. Message has no metadata field, so unknown keys are dropped.
-            build(**h.slice(*members))
+            content.map { |block| block.is_a?(ContentBlock) ? block : ContentBlock.from_hash(block) }
           end
 
-          # Wrap input: pass through if already a Message, parse if Hash.
-          def self.wrap(input)
-            return input if input.is_a?(Message)
-            return from_hash(input) if input.is_a?(Hash)
+          # L2: one tool-call normalizer shared by build and from_hash.
+          # Array<ToolCall> | nil (Array is canonical; the legacy Hash shape is gone).
+          def self.normalize_tool_calls!(tool_calls, site)
+            return nil if tool_calls.nil?
 
-            nil
+            Strict.expect_type!(tool_calls, [::Array], site, :tool_calls)
+            tool_calls.map { |tc| tc.is_a?(ToolCall) ? tc : ToolCall.from_hash(tc) }
           end
 
           # Extract plain text from content (String or ContentBlock array).
@@ -141,16 +116,25 @@ module Legion
             text
           end
 
-          # Minimal provider-facing hash (role + text content).
-          def to_provider_hash
-            { role: role.to_s, content: text }.compact
+          # H1: the single strict constructor — .new runs the same member
+          # contract as the factories (normalize or raise); the factories
+          # fill their defaults and delegate here. Missing members follow the
+          # nil contract of each member.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:role] = normalize_role!(values[:role], site)
+            values[:content] = normalize_content!(values[:content], site)
+            values[:tool_calls] = normalize_tool_calls!(values[:tool_calls], site)
+            values[:cache_control] = values[:cache_control].nil? ? nil : Strict.expect_type!(values[:cache_control], [::Hash], site, :cache_control)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
           end
         end
 
         Message::ROLES = %i[system user assistant tool].freeze
-        # rubocop:enable Lint/ConstantDefinitionInBlock
+        Message::BUILD_SITE = 'Canonical::Message.build'
+        Message::FROM_HASH_SITE = 'Canonical::Message.from_hash'
+        Message::NEW_SITE = 'Canonical::Message.new'
       end
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

data/lib/legion/extensions/llm/canonical/params.rb

@@ -3,49 +3,51 @@
 # -- from_hash normalization is intentional
 module Legion
   module Extensions
+    # -- module doc is in canonical.rb entry point
     module Llm
+      # -- required for Data.define block scope
       module Canonical
-        # rubocop:disable Lint/ConstantDefinitionInBlock -- required for Data.define block scope
         # Canonical sampling and limit parameters for a request.
         # Per G18: all standard/useful params are first-class, mapped per provider by translators.
+        # Canonical keys only (O03a): provider spellings are translated at the edges.
         Params = ::Data.define(
-          :max_tokens, :max_thinking_tokens, :temperature, :top_p, :top_k,
+          :max_tokens, :temperature, :top_p, :top_k,
           :stop_sequences, :seed, :frequency_penalty, :presence_penalty,
-          :response_format
+          :response_format, :metadata
         ) do
-          PARAMS_KNOWN_KEYS = %i[max_tokens max_thinking_tokens temperature top_p top_k
-                                 stop_sequences seed frequency_penalty presence_penalty
-                                 response_format].freeze
+          # rubocop:disable Metrics/ParameterLists -- factory methods have many params
+          # Build from keyword args (primary constructor).
+          def self.build(
+            max_tokens: nil, temperature: nil, top_p: nil, top_k: nil,
+            stop_sequences: nil, seed: nil, frequency_penalty: nil, presence_penalty: nil,
+            response_format: nil, metadata: {}
+          )
+            new(
+              max_tokens:, temperature:, top_p:, top_k:,
+              stop_sequences:, seed:, frequency_penalty:, presence_penalty:,
+              response_format:, metadata: Strict.metadata!(metadata, self::BUILD_SITE)
+            )
+          end
+          # rubocop:enable Metrics/ParameterLists
 
           # Build from a Hash (raw client request or deserialized wire payload).
-          # Accepts both canonical key names and common provider spellings.
+          # Canonical member keys only; unknown keys fold into metadata (04 L5).
+          # from_hash({}) is a valid all-nil Params (the no-params object), never nil.
           def self.from_hash(source)
-            return nil if source.nil? || source.empty?
-
-            h = source.transform_keys(&:to_sym)
-
-            # Normalize common provider key variations
-            h[:max_tokens] ||= h.delete(:max_output_tokens) || h.delete(:num_predict)
-            h[:max_thinking_tokens] ||= h.delete(:budget_tokens) || h.delete(:thinking_budget)
-            h[:stop_sequences] ||= h.delete(:stop)
-
-            # Filter to known keys only
-            filtered = h.slice(*PARAMS_KNOWN_KEYS)
-
-            # Return nil if all known values are nil
-            return nil if filtered.all? { |_, v| v.nil? }
-
-            new(
-              max_tokens: filtered[:max_tokens],
-              max_thinking_tokens: filtered[:max_thinking_tokens],
-              temperature: filtered[:temperature],
-              top_p: filtered[:top_p],
-              top_k: filtered[:top_k],
-              stop_sequences: filtered[:stop_sequences],
-              seed: filtered[:seed],
-              frequency_penalty: filtered[:frequency_penalty],
-              presence_penalty: filtered[:presence_penalty],
-              response_format: filtered[:response_format]
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(
+              max_tokens: hash[:max_tokens],
+              temperature: hash[:temperature],
+              top_p: hash[:top_p],
+              top_k: hash[:top_k],
+              stop_sequences: hash[:stop_sequences],
+              seed: hash[:seed],
+              frequency_penalty: hash[:frequency_penalty],
+              presence_penalty: hash[:presence_penalty],
+              response_format: hash[:response_format],
+              metadata:
             )
           end
 
@@ -62,8 +64,30 @@ module Legion
           def to_json(*)
             to_h.to_json(*)
           end
+
+          # H1/M3: the single strict constructor. .new validates every member
+          # against its wire type (Integer token counts and seeds, Numeric
+          # ratios and penalties, String|Array stop sequences, String|Hash
+          # response format) — garbage is rejected here, not on the provider
+          # wire. The factories fill their defaults and delegate here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:max_tokens] = Strict.expect_type!(values[:max_tokens], [::Integer], site, :max_tokens)
+            values[:temperature] = Strict.expect_type!(values[:temperature], [::Numeric], site, :temperature)
+            values[:top_p] = Strict.expect_type!(values[:top_p], [::Numeric], site, :top_p)
+            values[:top_k] = Strict.expect_type!(values[:top_k], [::Integer], site, :top_k)
+            values[:stop_sequences] = Strict.expect_type!(values[:stop_sequences], [::String, ::Array], site, :stop_sequences)
+            values[:seed] = Strict.expect_type!(values[:seed], [::Integer], site, :seed)
+            values[:frequency_penalty] = Strict.expect_type!(values[:frequency_penalty], [::Numeric], site, :frequency_penalty)
+            values[:presence_penalty] = Strict.expect_type!(values[:presence_penalty], [::Numeric], site, :presence_penalty)
+            values[:response_format] = Strict.expect_type!(values[:response_format], [::String, ::Hash], site, :response_format)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
         end
-        # rubocop:enable Lint/ConstantDefinitionInBlock
+
+        Params::BUILD_SITE = 'Canonical::Params.build'
+        Params::FROM_HASH_SITE = 'Canonical::Params.from_hash'
+        Params::NEW_SITE = 'Canonical::Params.new'
       end
     end
   end

data/lib/legion/extensions/llm/canonical/request.rb

@@ -2,13 +2,13 @@
 
 require 'securerandom'
 
-# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+# rubocop:disable-next Metrics/ParameterLists -- factory methods have many params
 module Legion
   module Extensions
     module Llm
       module Canonical
         # Canonical request shape — the single contract between client translators
-        # and the inference executor. Per R3 and G18.
+        # and the inference executor. Per R3 and G18. # -- required for Data.define block scope
         Request = ::Data.define(
           :id, :messages, :system, :tools, :tool_choice,
           :params, :thinking, :stream,
@@ -18,60 +18,74 @@ module Legion
           def self.build(
             id: nil, messages: nil, system: nil, tools: nil, tool_choice: nil,
             params: nil, thinking: nil, stream: false,
-            conversation_id: nil, caller: nil, routing: nil, metadata: nil
+            conversation_id: nil, caller: nil, routing: nil, metadata: {}
           )
-            # Normalize messages to Canonical::Message array
-            msg_array = Array(messages).filter_map do |msg|
-              msg.is_a?(Message) ? msg : Message.from_hash(msg)
-            end
-
-            # Normalize tools to Hash<name, ToolDefinition>
-            tool_hash = normalize_tools(tools)
-
-            # Normalize params
-            params_obj = case params
-                         when Params then params
-                         when Hash then Params.from_hash(params)
-                         end
-
-            # Normalize thinking config
-            thinking_obj = case thinking
-                           when Thinking::Config then thinking
-                           when Hash then Thinking::Config.new(**thinking.transform_keys(&:to_sym))
-                           end
-
             new(
               id: id || "req_#{SecureRandom.hex(12)}",
-              messages: msg_array,
+              messages: normalize_messages!(messages, self::BUILD_SITE),
               system: system,
-              tools: tool_hash,
-              tool_choice: tool_choice.is_a?(String) ? tool_choice.to_sym : tool_choice,
-              params: params_obj,
-              thinking: thinking_obj,
+              tools: normalize_tools(tools, self::BUILD_SITE),
+              tool_choice: tool_choice.is_a?(::String) ? tool_choice.to_sym : tool_choice,
+              params: normalize_params!(params, self::BUILD_SITE),
+              thinking: normalize_thinking!(thinking, self::BUILD_SITE),
               stream: stream,
               conversation_id: conversation_id,
               caller: caller,
               routing: routing || {},
-              metadata: metadata || {}
+              metadata: Strict.metadata!(metadata, self::BUILD_SITE)
             )
           end
 
           # Build from a Hash (raw client request or deserialized wire payload).
+          # Unknown keys fold into metadata — the model for 04 L5.
           def self.from_hash(source)
-            return nil if source.nil?
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(**hash, metadata:)
+          end
+
+          # 04 §9: strict message map — each element must be a Message (pass) or a
+          # Hash (normalize); anything else raises. No silent drops (F2 fix).
+          def self.normalize_messages!(messages, site)
+            return [] if messages.nil?
+
+            Strict.expect_type!(messages, [::Array], site, :messages)
+            messages.map { |msg| msg.is_a?(Message) ? msg : Message.from_hash(msg) }
+          end
 
-            h = source.transform_keys(&:to_sym)
+          # L2: the single tools normalizer, shared by build and from_hash.
+          # Hash<name, ToolDefinition> or Array<ToolDefinition|Hash>; anything else raises.
+          def self.normalize_tools(tools, site)
+            return {} if tools.nil? || tools.empty?
 
-            # Extract metadata from unknown keys
-            metadata = h[:metadata] || {}
-            known_keys = %i[id messages system tools tool_choice params thinking
-                            stream conversation_id caller routing metadata]
-            (h.keys - known_keys).each do |key|
-              metadata[key] = h.delete(key)
+            case tools
+            when Hash
+              tools.transform_values { |tool| tool.is_a?(ToolDefinition) ? tool : ToolDefinition.from_hash(tool) }
+            when Array
+              tools.each_with_object({}) do |tool, hash|
+                td = tool.is_a?(ToolDefinition) ? tool : ToolDefinition.from_hash(tool)
+                hash[td.name] = td
+              end
+            else
+              Strict.expect_type!(tools, [::Hash, ::Array], site, :tools)
             end
-            h[:metadata] = metadata
+          end
+
+          def self.normalize_params!(params, site)
+            return nil if params.nil?
+            return params if params.is_a?(Params)
+
+            Strict.expect_type!(params, [::Hash], site, :params)
+            Params.from_hash(params)
+          end
+
+          def self.normalize_thinking!(thinking, site)
+            return nil if thinking.nil?
+            return thinking if thinking.is_a?(Thinking::Config)
 
-            build(**h)
+            Strict.expect_type!(thinking, [::Hash], site, :thinking)
+            Thinking::Config.from_hash(thinking)
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
@@ -101,26 +115,24 @@ module Legion
             to_h.to_json(*)
           end
 
-          def self.normalize_tools(tools)
-            return {} if tools.nil? || tools.empty?
-
-            case tools
-            when Hash
-              tools.transform_values do |tool|
-                tool.is_a?(ToolDefinition) ? tool : ToolDefinition.from_hash(tool)
-              end
-            when Array
-              tools.each_with_object({}) do |tool, hash|
-                td = tool.is_a?(ToolDefinition) ? tool : ToolDefinition.from_hash(tool)
-                hash[td.name] = td
-              end
-            else
-              {}
-            end
+          # H1: the single strict constructor — .new runs the same member
+          # contract as the factories; the factories fill their defaults and
+          # delegate here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:messages] = normalize_messages!(values[:messages], site)
+            values[:tools] = normalize_tools(values[:tools], site)
+            values[:tool_choice] = values[:tool_choice].is_a?(::String) ? values[:tool_choice].to_sym : values[:tool_choice]
+            values[:params] = normalize_params!(values[:params], site)
+            values[:thinking] = normalize_thinking!(values[:thinking], site)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
           end
         end
+
+        Request::BUILD_SITE = 'Canonical::Request.build'
+        Request::FROM_HASH_SITE = 'Canonical::Request.from_hash'
+        Request::NEW_SITE = 'Canonical::Request.new'
       end
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists