lex-llm 0.7.3 → 0.8.0

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

@@ -4,104 +4,75 @@
 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 response shape — the provider-boundary contract.
         # Per R2: does NOT replace Inference::Response (the pipeline envelope).
         # Per Amendment A: immutable Data.define with strict factory.
+        # Unknown keys fold into metadata — never silently dropped.
         Response = ::Data.define(
           :text, :thinking, :tool_calls, :usage,
           :stop_reason, :model, :routing, :metadata
         ) do
-          STOP_REASONS = %i[end_turn tool_use max_tokens stop_sequence content_filter error].freeze
+          # Build from keyword args (primary constructor).
+          def self.build(
+            text: '', thinking: nil, tool_calls: nil, usage: nil,
+            stop_reason: nil, model: nil, routing: nil, metadata: {}
+          )
+            new(
+              text: text.to_s,
+              thinking: normalize_thinking!(thinking, self::BUILD_SITE),
+              tool_calls: normalize_tool_calls!(tool_calls, self::BUILD_SITE),
+              usage: normalize_usage!(usage, self::BUILD_SITE),
+              stop_reason: normalize_stop_reason!(stop_reason, self::BUILD_SITE),
+              model: model,
+              routing: routing || {},
+              metadata: Strict.metadata!(metadata, self::BUILD_SITE)
+            )
+          end
 
           # Build from a Hash (raw provider response or deserialized wire payload).
-          # Unknown keys go to metadata, never silently dropped.
+          # Canonical keys only (O03a): edges pass `stop_reason`, not `finish_reason`.
           def self.from_hash(source)
-            return nil if source.nil?
-
-            h = source.transform_keys(&:to_sym)
-
-            # Extract known fields
-            text = h.delete(:text) || h.delete(:content) || ''
-            text = text.to_s if text
-
-            thinking_raw = h.delete(:thinking)
-            thinking = thinking_raw.is_a?(Thinking) ? thinking_raw : Thinking.from_hash(thinking_raw)
-
-            tool_calls_raw = h.delete(:tool_calls)
-            tool_calls = Array(tool_calls_raw).filter_map do |tc|
-              tc.is_a?(ToolCall) ? tc : ToolCall.from_hash(tc)
-            end
+            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
 
-            usage_raw = h.delete(:usage)
-            usage = usage_raw.is_a?(Usage) ? usage_raw : Usage.from_hash(usage_raw)
+          # L6: stop_reason validated at construction, in both factories.
+          def self.normalize_stop_reason!(stop_reason, site)
+            stop_reason_sym = stop_reason&.to_sym
+            Strict.enum!(stop_reason_sym, self::STOP_REASONS, site, :stop_reason)
+          end
 
-            # Normalize stop_reason
-            stop_reason_raw = h.delete(:stop_reason) || h.delete(:finish_reason)
-            stop_reason = stop_reason_raw&.to_sym if stop_reason_raw
-            unless stop_reason.nil? || STOP_REASONS.include?(stop_reason)
-              raise ArgumentError,
-                    "Invalid stop_reason: #{stop_reason.inspect}. Must be one of: #{STOP_REASONS.join(', ')}"
-            end
+          # L2: one normalizer per member, shared by build and from_hash.
+          def self.normalize_thinking!(thinking, site)
+            return nil if thinking.nil?
+            return thinking if thinking.is_a?(Thinking)
 
-            model = h.delete(:model)
-            routing = h.delete(:routing) || {}
+            Strict.expect_type!(thinking, [::Hash], site, :thinking)
+            Thinking.from_hash(thinking)
+          end
 
-            # Remaining keys become metadata
-            existing_metadata = h.delete(:metadata) || {}
-            metadata = existing_metadata.merge(h).compact
+          def self.normalize_tool_calls!(tool_calls, site)
+            return [] if tool_calls.nil?
 
-            new(
-              text: text,
-              thinking: thinking,
-              tool_calls: tool_calls,
-              usage: usage,
-              stop_reason: stop_reason,
-              model: model,
-              routing: routing,
-              metadata: metadata
-            )
+            Strict.expect_type!(tool_calls, [::Array], site, :tool_calls)
+            tool_calls.map { |tc| tc.is_a?(ToolCall) ? tc : ToolCall.from_hash(tc) }
           end
 
-          # Build from keyword args (primary constructor).
-          def self.build(
-            text: '', thinking: nil, tool_calls: nil, usage: nil,
-            stop_reason: nil, model: nil, routing: nil, metadata: nil
-          )
-            stop_reason_sym = stop_reason&.to_sym
-            unless stop_reason_sym.nil? || STOP_REASONS.include?(stop_reason_sym)
-              raise ArgumentError,
-                    "Invalid stop_reason: #{stop_reason_sym.inspect}. Must be one of: #{STOP_REASONS.join(', ')}"
-            end
+          def self.normalize_usage!(usage, site)
+            return nil if usage.nil?
+            return usage if usage.is_a?(Usage)
 
-            new(
-              text: text.to_s,
-              thinking: thinking,
-              tool_calls: tool_calls || [],
-              usage: usage,
-              stop_reason: stop_reason_sym,
-              model: model,
-              routing: routing || {},
-              metadata: metadata || {}
-            )
+            Strict.expect_type!(usage, [::Hash], site, :usage)
+            Usage.from_hash(usage)
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
           def to_h
-            {
-              text: text,
-              thinking: thinking&.to_h,
-              tool_calls: tool_calls&.map { |tc| tc.is_a?(ToolCall) ? tc.to_h : tc },
-              usage: usage&.to_h,
-              stop_reason: stop_reason,
-              model: model,
-              routing: routing,
-              metadata: metadata
-            }.compact.reject do |k, v|
-              %i[tool_calls routing
-                 metadata].include?(k) && v.is_a?(Enumerable) && v.empty?
-            end
+            super.compact
           end
 
           # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
@@ -122,10 +93,24 @@ module Legion
           def error?
             stop_reason == :error
           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[:thinking] = normalize_thinking!(values[:thinking], site)
+            values[:tool_calls] = normalize_tool_calls!(values[:tool_calls], site)
+            values[:usage] = normalize_usage!(values[:usage], site)
+            values[:stop_reason] = normalize_stop_reason!(values[:stop_reason], site)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
         end
 
         Response::STOP_REASONS = %i[end_turn tool_use max_tokens stop_sequence content_filter error].freeze
-        # rubocop:enable Lint/ConstantDefinitionInBlock
+        Response::BUILD_SITE = 'Canonical::Response.build'
+        Response::FROM_HASH_SITE = 'Canonical::Response.from_hash'
+        Response::NEW_SITE = 'Canonical::Response.new'
       end
     end
   end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# -- module doc is in canonical.rb entry point
+module Legion
+  module Extensions
+    module Llm
+      # -- required for Data.define block scope
+      module Canonical
+        # Shared strict-factory guards (04 L1/L3/L5/L6) — one implementation for
+        # every type. Nil or wrong-class input raises ArgumentError naming the
+        # site, member, and offending class. No factory returns nil; unknown
+        # keys fold into the metadata member (no drops, no raises).
+        #
+        # H1: every type installs a validated `.new` (a single strict
+        # constructor). `.new`, `.build`, and `.from_hash` all run the same
+        # member contract — a `.new`-minted object cannot carry poison past
+        # the class-membership boundaries (enforce_canonical_messages!,
+        # fleet W4 rehydration, the conformance kit).
+        module Strict
+          module_function
+
+          # H1: install the strict `.new` on a Data type. The C-level
+          # constructor is preserved as the PRIVATE `data_define_new` (used
+          # only by the strict `.new` itself); the public `.new` maps the
+          # call shape (member_values!), runs the type's member contract
+          # (validate, a ->(values, site) block returning the normalized
+          # values), and delegates. Every construction path — .new, .build,
+          # .from_hash — funnels through the same contract.
+          def install_strict_new!(type_class, &validate)
+            singleton = type_class.singleton_class
+            singleton.alias_method(:data_define_new, :new)
+            singleton.send(:private, :data_define_new)
+
+            singleton.define_method(:new) do |*args, **kwargs|
+              values = Strict.member_values!(self, self::NEW_SITE, args, kwargs)
+              values = validate.call(values, self::NEW_SITE)
+              data_define_new(**values)
+            end
+          end
+
+          # Map raw `.new` arguments (positional or keyword form) onto a
+          # member => value Hash. Wrong call shapes raise a typed
+          # ArgumentError naming the site: mixing both forms, a positional
+          # count mismatch, or an unknown member. Members absent from the
+          # call map to nil and follow each member's own contract.
+          def member_values!(type_class, site, args, kwargs)
+            members = type_class.members
+            raise ArgumentError, "#{site}: pass either positional or keyword members, not both" if args.any? && kwargs.any?
+
+            if args.any?
+              raise ArgumentError, "#{site}: expected #{members.size} positional members, got #{args.size}" unless args.size == members.size
+
+              return members.zip(args).to_h
+            end
+
+            unknown = kwargs.keys - members.map(&:to_sym)
+            raise ArgumentError, "#{site}: unknown member(s) #{unknown.sort.join(', ')}" unless unknown.empty?
+
+            members.to_h { |member| [member, kwargs[member]] }
+          end
+
+          def require_hash!(source, site)
+            return source if source.is_a?(::Hash)
+
+            raise ArgumentError, "#{site}: expected Hash, got #{source.class}"
+          end
+
+          def symbolize_keys(hash)
+            hash.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+          end
+
+          # 04 L5: unknown keys fold into the metadata member.
+          def fold_unknowns!(type_class, site, hash)
+            metadata = metadata!(hash.delete(:metadata), site)
+            known = type_class.members.map(&:to_sym)
+            (hash.keys - known).each { |key| metadata[key] = hash.delete(key) }
+            metadata
+          end
+
+          def metadata!(value, site, member: :metadata)
+            return {} if value.nil?
+
+            raise ArgumentError, "#{site}: #{member} expected Hash, got #{value.class}" unless value.is_a?(::Hash)
+
+            value
+          end
+
+          def enum!(value, allowed, site, member)
+            return value if value.nil? || allowed.include?(value)
+
+            raise ArgumentError,
+                  "#{site}: Invalid #{member}: #{value.inspect}. Must be one of: #{allowed.join(', ')}"
+          end
+
+          def expect_type!(value, allowed, site, member)
+            return value if value.nil? || allowed.any? { |klass| value.is_a?(klass) }
+
+            raise ArgumentError,
+                  "#{site}: #{member} expected #{allowed.map(&:name).join(' | ')}, got #{value.class}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,27 +3,37 @@
 # -- from_hash normalization is intentional
 module Legion
   module Extensions
+    # -- module doc is in canonical.rb entry point
     module Llm
-      # rubocop:disable Style/Documentation -- module doc is in canonical.rb entry point
+      # -- required for Data.define block scope
       module Canonical
         # Canonical thinking/reasoning block.
         # Ports field vocabulary from Legion::LLM::Types and lex-llm Thinking.
-        Thinking = ::Data.define(:content, :signature) do
+        # Empty-string values normalize to nil (absence, not data — 04 §8).
+        Thinking = ::Data.define(:content, :signature, :metadata) do
+          # Build from keyword args (primary constructor).
+          def self.build(content: nil, signature: nil, metadata: {})
+            new(
+              content: absence!(content, self::BUILD_SITE, :content),
+              signature: absence!(signature, self::BUILD_SITE, :signature),
+              metadata: Strict.metadata!(metadata, self::BUILD_SITE)
+            )
+          end
+
           # Build from a Hash (raw provider response or deserialized wire payload).
           def self.from_hash(source)
-            return nil if source.nil?
-
-            h = source.transform_keys(&:to_sym)
-
-            # Treat empty strings as nil
-            content = h[:content]
-            content = nil if content.is_a?(String) && content.empty?
-            signature = h[:signature]
-            signature = nil if signature.is_a?(String) && signature.empty?
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(content: hash[:content], signature: hash[:signature], metadata:)
+          end
 
-            return nil if content.nil? && signature.nil?
+          # Empty-string is absence, not data (04 §8).
+          def self.absence!(value, site, member)
+            return nil if value.nil?
 
-            new(content: content, signature: signature)
+            Strict.expect_type!(value, [::String], site, member)
+            value.empty? ? nil : value
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
@@ -44,46 +54,64 @@ module Legion
           def empty?
             content.nil? && signature.nil?
           end
-        end
-
-        # Normalized config for thinking across providers.
-        # Mirrors lex-llm Thinking::Config.
-        class ThinkingConfig
-          INCLUDES = Thinking
 
-          # SSOT for the effort<->budget conversion. A client dialect supplies only
-          # ONE axis (Anthropic = budget_tokens only; OpenAI = effort only), but a
-          # provider translator may need the OTHER. This single map lets every
-          # provider ask for whichever axis it needs and always get a usable value,
-          # so thinking survives any client x provider pair (best-effort, never
-          # silently dropped). effort -> budget is exact; budget -> effort uses the
-          # band boundaries below.
-          EFFORT_BUDGET = { 'low' => 1024, 'medium' => 8192, 'high' => 16_384 }.freeze
-
-          attr_reader :effort, :budget
-
-          def initialize(effort: nil, budget: nil)
-            @effort = effort.is_a?(Symbol) ? effort.to_s : effort
-            @budget = budget
+          # 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[:content] = absence!(values[:content], site, :content)
+            values[:signature] = absence!(values[:signature], site, :signature)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
           end
+        end
 
-          # Build from keyword args.
-          def self.build(effort: nil, budget: nil)
-            new(effort: effort, budget: budget)
+        Thinking::BUILD_SITE = 'Canonical::Thinking.build'
+        Thinking::FROM_HASH_SITE = 'Canonical::Thinking.from_hash'
+        Thinking::NEW_SITE = 'Canonical::Thinking.new'
+
+        # Normalized config for thinking across providers — one name, one shape
+        # (04 §8): Canonical::Thinking::Config. # -- required for Data.define block scope
+        Thinking::Config = ::Data.define(:effort, :budget, :metadata) do
+          def self.build(effort: nil, budget: nil, metadata: {})
+            new(effort: effort_string!(effort, self::BUILD_SITE), budget:,
+                metadata: Strict.metadata!(metadata, self::BUILD_SITE))
           end
 
           # Build from a Hash.
           def self.from_hash(source)
-            return nil if source.nil? || source.empty?
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(effort: hash[:effort], budget: hash[:budget], metadata:)
+          end
+
+          # M4: effort is a closed enum (the EFFORT_BUDGET keys), not an
+          # unbounded string — an unrecognized effort is a contract error at
+          # construction, never a silently-derived budget.
+          def self.effort_string!(effort, site)
+            return nil if effort.nil?
+
+            value = effort.is_a?(::Symbol) ? effort.to_s : Strict.expect_type!(effort, [::String], site, :effort)
+            normalized = value.downcase
+            allowed = self::EFFORT_BUDGET.keys
+            raise ArgumentError, "#{site}: Invalid effort: #{value.inspect}. Must be one of: #{allowed.join(', ')}" unless allowed.include?(normalized)
 
-            h = source.transform_keys(&:to_sym)
-            build(effort: h[:effort], budget: h[:budget])
+            normalized
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport. Faithful to what was
           # SET — never fabricates the missing axis (use resolved_* for that).
           def to_h
-            { effort: effort, budget: budget }.compact
+            super.compact
+          end
+
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
           end
 
           # Whether thinking is configured.
@@ -92,34 +120,54 @@ module Legion
           end
 
           # Budget for a provider that needs a token budget (e.g. Anthropic),
-          # derived from effort when budget was not explicitly set. nil only when
-          # neither axis is configured.
+          # derived from effort when budget was not explicitly set. nil only
+          # when neither axis is configured. M4: effort is enum-validated at
+          # construction, so the lookup cannot miss — the silent medium
+          # fallback is deleted.
           def resolved_budget
             return budget unless budget.nil?
             return nil if effort.nil?
 
-            EFFORT_BUDGET[effort.to_s.downcase] || EFFORT_BUDGET['medium']
+            self.class::EFFORT_BUDGET[effort]
           end
 
           # Effort for a provider that needs an effort level (e.g. OpenAI),
-          # derived from budget when effort was not explicitly set. nil only when
-          # neither axis is configured.
+          # derived from budget when effort was not explicitly set. nil only
+          # when neither axis is configured.
           def resolved_effort
             return effort unless effort.nil?
             return nil if budget.nil?
 
-            b = budget.to_i
-            if b < EFFORT_BUDGET['medium'] then 'low'
-            elsif b < EFFORT_BUDGET['high'] then 'medium'
+            bands = self.class::EFFORT_BUDGET
+            if budget < bands['medium'] then 'low'
+            elsif budget < bands['high'] then 'medium'
             else 'high'
             end
           end
+
+          # H1/M4: the single strict constructor — .new runs the same member
+          # contract as the factories (effort enum, Integer budget); the
+          # factories fill their defaults and delegate here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:effort] = effort_string!(values[:effort], site)
+            values[:budget] = Strict.expect_type!(values[:budget], [::Integer], site, :budget)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
         end
 
-        # Alias for convenience: Canonical::Thinking::Config
-        Thinking.const_set(:Config, ThinkingConfig)
+        # SSOT for the effort<->budget conversion. A client dialect supplies only
+        # ONE axis (Anthropic = budget_tokens only; OpenAI = effort only), but a
+        # provider translator may need the OTHER. This single map lets every
+        # provider ask for whichever axis it needs and always get a usable value,
+        # so thinking survives any client x provider pair (best-effort, never
+        # silently dropped). effort -> budget is exact; budget -> effort uses the
+        # band boundaries above.
+        Thinking::Config::EFFORT_BUDGET = { 'low' => 1024, 'medium' => 8192, 'high' => 16_384 }.freeze
+        Thinking::Config::BUILD_SITE = 'Canonical::Thinking::Config.build'
+        Thinking::Config::FROM_HASH_SITE = 'Canonical::Thinking::Config.from_hash'
+        Thinking::Config::NEW_SITE = 'Canonical::Thinking::Config.new'
       end
-      # rubocop:enable Style/Documentation
     end
   end
 end

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

@@ -6,35 +6,36 @@ require 'securerandom'
 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 tool call with source enum and compliance fields.
         # Ports field vocabulary from Legion::LLM::Types::ToolCall.
         # Source enum per R7: :client | :registry | :special | :extension | :mcp
         # Compliance fields per R8: data_handling_classification, policy_decision
+        # arguments is a Hash only (O03a): JSON-string arguments are a provider
+        # wire spelling parsed at the provider translator edge (10 U2).
         ToolCall = ::Data.define(
           :id, :exchange_id, :name, :arguments, :source,
           :status, :duration_ms, :result, :error,
           :started_at, :finished_at, :category,
-          :data_handling_classification, :policy_decision
+          :data_handling_classification, :policy_decision, :metadata
         ) do
-          SOURCE_VALUES = %i[client registry special extension mcp].freeze
-          STATUS_VALUES = %i[pending running success error].freeze
-
           # Build from keyword args (primary constructor).
+          # arguments: nil means "no arguments" and normalizes to {} (documented
+          # default, not tolerance).
           def self.build(
             name:, id: nil, exchange_id: nil, arguments: nil, source: nil,
             status: nil, duration_ms: nil, result: nil, error: nil,
             started_at: nil, finished_at: nil, category: nil,
-            data_handling_classification: nil, policy_decision: nil
+            data_handling_classification: nil, policy_decision: nil, metadata: {}
           )
             new(
               id: id || "call_#{SecureRandom.hex(12)}",
               exchange_id: exchange_id,
-              name: name,
-              arguments: arguments || {},
-              source: source,
-              status: status,
+              name: Strict.expect_type!(name, [::String], self::BUILD_SITE, :name),
+              arguments: arguments.nil? ? {} : Strict.expect_type!(arguments, [::Hash], self::BUILD_SITE, :arguments),
+              source: normalize_enum!(source, self::SOURCE_VALUES, self::BUILD_SITE, :source),
+              status: normalize_enum!(status, self::STATUS_VALUES, self::BUILD_SITE, :status),
               duration_ms: duration_ms,
               result: result,
               error: error,
@@ -42,38 +43,30 @@ module Legion
               finished_at: finished_at,
               category: category,
               data_handling_classification: data_handling_classification,
-              policy_decision: policy_decision
+              policy_decision: policy_decision,
+              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 source to symbol
-            source_raw = h[:source]
-            h[:source] = source_raw&.to_sym if source_raw.is_a?(String)
-
-            # Normalize status to symbol
-            status_raw = h[:status]
-            h[:status] = status_raw&.to_sym if status_raw.is_a?(String)
+          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
 
-            # Parse arguments if they're a JSON string
-            args = h[:arguments]
-            if args.is_a?(String) && !args.empty?
-              begin
-                h[:arguments] = Legion::JSON.load(args)
-              rescue Legion::JSON::ParseError => e
-                Legion::Logging.debug("[lex-llm][canonical][tool_call] arguments not parseable as JSON, leaving as string: #{e.message}")
-              end
-            end
+          # L6: declared enums validated at construction, in both factories.
+          def self.normalize_enum!(value, allowed, site, member)
+            return nil if value.nil?
 
-            build(**h)
+            value_sym = value.is_a?(::String) ? value.to_sym : value
+            Strict.enum!(value_sym, allowed, site, member)
           end
 
-          # Return a new ToolCall with execution result attached.
+          # Return a new ToolCall with execution result attached. The strict
+          # constructor re-validates every carried member (status enum
+          # included) — the escape-hatch .new of the pre-H1 world is gone.
           def with_result(result:, status:, duration_ms: nil, finished_at: nil)
             self.class.new(
               id: id,
@@ -89,7 +82,8 @@ module Legion
               finished_at: finished_at || ::Time.now,
               category: category,
               data_handling_classification: data_handling_classification,
-              policy_decision: policy_decision
+              policy_decision: policy_decision,
+              metadata: metadata
             )
           end
 
@@ -116,27 +110,24 @@ module Legion
             to_h.to_json(*)
           end
 
-          # Subset for audit/ledger emission.
-          def to_audit_hash
-            {
-              id: id,
-              name: name,
-              arguments: arguments,
-              status: status,
-              duration_ms: duration_ms,
-              error: error,
-              exchange_id: exchange_id,
-              source: source,
-              category: category,
-              data_handling_classification: data_handling_classification,
-              policy_decision: policy_decision
-            }.compact
+          # 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[:name] = Strict.expect_type!(values[:name], [::String], site, :name)
+            values[:arguments] = values[:arguments].nil? ? {} : Strict.expect_type!(values[:arguments], [::Hash], site, :arguments)
+            values[:source] = normalize_enum!(values[:source], self::SOURCE_VALUES, site, :source)
+            values[:status] = normalize_enum!(values[:status], self::STATUS_VALUES, site, :status)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
           end
         end
 
         ToolCall::SOURCE_VALUES = %i[client registry special extension mcp].freeze
         ToolCall::STATUS_VALUES = %i[pending running success error].freeze
-        # rubocop:enable Lint/ConstantDefinitionInBlock
+        ToolCall::BUILD_SITE = 'Canonical::ToolCall.build'
+        ToolCall::FROM_HASH_SITE = 'Canonical::ToolCall.from_hash'
+        ToolCall::NEW_SITE = 'Canonical::ToolCall.new'
       end
     end
   end