lex-llm 0.7.3 → 0.8.0

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

@@ -4,21 +4,20 @@ module Legion
   module Extensions
     module Llm
       module Canonical
-        TOOL_NAME_MAX_LENGTH = 64
         OBJECT_SCHEMA_KEYWORDS    = %i[properties required additionalProperties].freeze
         COMPOSITE_SCHEMA_KEYWORDS = %i[oneOf anyOf allOf enum $ref $defs definitions].freeze
 
         # Canonical tool definition.
-        # Ports field vocabulary from Legion::LLM::Types::ToolDefinition.
-        ToolDefinition = ::Data.define(:name, :description, :parameters, :source) do
+        # Ports field vocabulary from Legion::LLM::Types::ToolDefinition. # -- required for Data.define block scope
+        ToolDefinition = ::Data.define(:name, :description, :parameters, :source, :metadata) do
           def self.normalize_parameters(parameters)
             empty = { type: 'object', properties: {} }
             return empty if parameters.nil?
 
-            schema = if parameters.respond_to?(:transform_keys)
-                       parameters.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
-                     end
-            return empty if schema.nil? || schema.empty?
+            Strict.expect_type!(parameters, [::Hash], self::NORMALIZE_PARAMETERS_SITE, :parameters) unless parameters.is_a?(::Hash)
+
+            schema = parameters.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+            return empty if schema.empty?
             return schema if schema.key?(:type)
             return schema.merge(type: 'object') if OBJECT_SCHEMA_KEYWORDS.any? { |k| schema.key?(k) }
             return schema if COMPOSITE_SCHEMA_KEYWORDS.any? { |k| schema.key?(k) }
@@ -26,53 +25,50 @@ module Legion
             { type: 'object', properties: schema }
           end
 
-          # Build from keyword args (primary constructor).
-          def self.build(name:, description: '', parameters: nil, source: nil)
+          # Build from keyword args (primary constructor). M5: the name is the
+          # authoritative client/registry fact — never rewritten, stripped,
+          # truncated, or fabricated here; per-dialect name constraints belong
+          # to the provider translator edge. source is explicit or absent —
+          # never fabricated ({ type: :builtin } is deleted).
+          def self.build(name:, description: '', parameters: nil, source: nil, metadata: {})
             new(
-              sanitize_tool_name(name),
-              description.to_s,
+              name,
+              description,
               normalize_parameters(parameters),
-              source || { type: :builtin }
+              source,
+              Strict.metadata!(metadata, self::BUILD_SITE)
             )
           end
 
           # Build from a Hash (raw provider response or deserialized wire payload).
-          def self.from_hash(hash, source: nil)
-            return nil if hash.nil?
-
-            normalized = hash.respond_to?(:transform_keys) ? hash.transform_keys(&:to_sym) : {}
+          # Canonical keys only (O03a): edges pass `parameters`, not `input_schema`.
+          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(
-              name: normalized[:name],
-              description: normalized[:description],
-              parameters: normalized[:parameters] || normalized[:input_schema],
-              source: source || normalized[:source]
+              name: hash[:name],
+              description: hash[:description],
+              parameters: hash[:parameters],
+              source: hash[:source],
+              metadata:
             )
           end
 
-          # Build from a registry entry (extension/registry tool metadata).
-          def self.from_registry_entry(entry)
-            source = {
-              type: entry[:tool_class] ? :registry : :extension,
-              tool_class: entry[:tool_class],
-              extension: entry[:extension],
-              runner: entry[:runner],
-              function: entry[:function]
-            }.compact
+          # M5: a tool name is authoritative — missing or empty is a contract
+          # error, never a fabricated label.
+          def self.require_name!(name, site)
+            raise ArgumentError, "#{site}: name must be a non-empty String, got #{name.class}: #{name.inspect}" unless name.is_a?(::String) && !name.empty?
 
-            build(
-              name: entry[:name],
-              description: entry[:description],
-              parameters: entry[:input_schema] || entry[:parameters],
-              source: source.compact
-            )
+            name
           end
 
-          # Sanitize a tool name to be safe for all wire formats.
-          def self.sanitize_tool_name(raw)
-            name = raw.to_s.tr('.', '_')
-            name = name.gsub(/[^a-zA-Z0-9_-]/, '')
-            name = name[0, TOOL_NAME_MAX_LENGTH] if name.length > TOOL_NAME_MAX_LENGTH
-            name.empty? ? 'tool' : name
+          # M5: description is a String; absence is the empty string (the
+          # documented no-description value), wrong class raises.
+          def self.description_value!(description, site)
+            return '' if description.nil?
+
+            Strict.expect_type!(description, [::String], site, :description)
           end
 
           def params_schema
@@ -85,11 +81,7 @@ module Legion
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
           def to_h
-            {
-              name: name,
-              description: description,
-              parameters: parameters
-            }.compact.reject { |k, v| k == :description && v == '' }
+            super.compact
           end
 
           # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
@@ -100,7 +92,25 @@ module Legion
           def to_json(*)
             to_h.to_json(*)
           end
+
+          # H1/M5: the single strict constructor — .new runs the same member
+          # contract as the factories (authoritative name, String
+          # description, normalized parameters, explicit-or-absent source);
+          # the factories fill their defaults and delegate here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:name] = require_name!(values[:name], site)
+            values[:description] = description_value!(values[:description], site)
+            values[:parameters] = normalize_parameters(values[:parameters])
+            values[:source] = Strict.expect_type!(values[:source], [::Hash], site, :source)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
         end
+
+        ToolDefinition::BUILD_SITE = 'Canonical::ToolDefinition.build'
+        ToolDefinition::FROM_HASH_SITE = 'Canonical::ToolDefinition.from_hash'
+        ToolDefinition::NEW_SITE = 'Canonical::ToolDefinition.new'
+        ToolDefinition::NORMALIZE_PARAMETERS_SITE = 'Canonical::ToolDefinition.normalize_parameters'
       end
     end
   end

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

@@ -4,40 +4,33 @@ module Legion
   module Extensions
     module Llm
       module Canonical
-        # Extracts and normalizes tool schemas from heterogeneous sources.
+        # Extracts and normalizes tool schemas from ToolDefinition ONLY (04 §6).
+        # A schema extractor that tolerates raw hashes is a hidden path over the
+        # canonical type — wrong-class input raises (L3).
         module ToolSchema
           EMPTY_OBJECT = { type: 'object', properties: {} }.freeze
 
           module_function
 
-          def extract(tool)
-            raw = raw_schema(tool)
-            ToolDefinition.normalize_parameters(raw)
+          def extract(tool_definition)
+            require_tool_definition!(tool_definition, 'ToolSchema.extract')
+            ToolDefinition.normalize_parameters(tool_definition.parameters)
           end
 
-          def raw_schema(tool)
-            return nil if tool.nil?
-            return tool.params_schema if tool.respond_to?(:params_schema) && tool.params_schema
-            return tool.parameters if tool.respond_to?(:parameters) && tool.parameters
-
-            return unless tool.respond_to?(:[])
-
-            tool[:parameters] || tool['parameters'] || tool[:input_schema] || tool['input_schema'] ||
-              tool[:params_schema] || tool['params_schema']
+          def tool_name(tool_definition)
+            require_tool_definition!(tool_definition, 'ToolSchema.tool_name')
+            tool_definition.name
           end
 
-          def tool_name(tool)
-            return tool.name if tool.respond_to?(:name) && !tool.is_a?(Hash)
-            return tool[:name] || tool['name'] if tool.respond_to?(:[])
-
-            'unknown'
+          def tool_description(tool_definition)
+            require_tool_definition!(tool_definition, 'ToolSchema.tool_description')
+            tool_definition.description
           end
 
-          def tool_description(tool)
-            return tool.description if tool.respond_to?(:description) && !tool.is_a?(Hash)
-            return (tool[:description] || tool['description'] || '').to_s if tool.respond_to?(:[])
+          def require_tool_definition!(tool_definition, site)
+            return tool_definition if tool_definition.is_a?(ToolDefinition)
 
-            ''
+            raise ArgumentError, "#{site}: expected Canonical::ToolDefinition, got #{tool_definition.class}"
           end
         end
       end

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

@@ -4,56 +4,44 @@
 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 usage/metering data for a response.
         # Ports field vocabulary from lex-llm Tokens and legion-llm Types.
         # Includes non-token units extension point per G20b.
+        # Canonical keys only (O03a): provider spellings are translated at the edges.
         Usage = ::Data.define(
           :input_tokens, :output_tokens, :cache_read_tokens, :cache_write_tokens,
-          :thinking_tokens, :units
+          :thinking_tokens, :units, :metadata
         ) do
-          USAGE_KNOWN_KEYS = %i[input_tokens output_tokens cache_read_tokens cache_write_tokens
-                                thinking_tokens units].freeze
-
-          # Build from a Hash (raw provider response or deserialized wire payload).
-          # Accepts both canonical key names and legacy provider spellings.
-          def self.from_hash(source)
-            return nil if source.nil? || source.empty?
-
-            h = source.transform_keys(&:to_sym)
-
-            # Normalize legacy key names
-            h[:input_tokens] ||= h.delete(:input) || h.delete(:prompt_tokens)
-            h[:output_tokens] ||= h.delete(:output) || h.delete(:completion_tokens)
-            h[:cache_read_tokens] ||= h.delete(:cached) || h.delete(:cache_read)
-            h[:cache_write_tokens] ||= h.delete(:cache_creation) || h.delete(:cache_write)
-            h[:thinking_tokens] ||= h.delete(:thinking) || h.delete(:reasoning)
-
-            # Extract nested details (OpenAI prompt_tokens_details / input_tokens_details)
-            h[:cache_read_tokens] ||= dig_nested(h, :prompt_tokens_details, :cached_tokens) ||
-                                      dig_nested(h, :input_tokens_details, :cached_tokens)
-            h[:thinking_tokens] ||= dig_nested(h, :completion_tokens_details, :reasoning_tokens) ||
-                                    dig_nested(h, :output_tokens_details, :reasoning_tokens)
-
-            # Extract units (non-token extension point — G20b)
-            units = h.delete(:units) || {}
-
+          # rubocop:disable Metrics/ParameterLists -- factory methods have many params
+          # Build from keyword args (primary constructor).
+          def self.build(
+            input_tokens: nil, output_tokens: nil, cache_read_tokens: nil,
+            cache_write_tokens: nil, thinking_tokens: nil, units: nil, metadata: {}
+          )
             new(
-              input_tokens: h[:input_tokens],
-              output_tokens: h[:output_tokens],
-              cache_read_tokens: h[:cache_read_tokens],
-              cache_write_tokens: h[:cache_write_tokens],
-              thinking_tokens: h[:thinking_tokens],
-              units: units
+              input_tokens:, output_tokens:, cache_read_tokens:, cache_write_tokens:,
+              thinking_tokens:, units: units || {}, metadata: Strict.metadata!(metadata, self::BUILD_SITE)
             )
           end
+          # rubocop:enable Metrics/ParameterLists
 
-          def self.dig_nested(hash, details_key, value_key)
-            details = hash[details_key]
-            return nil unless details.is_a?(Hash)
-
-            details[value_key] || details[value_key.to_s]
+          # Build from a Hash (raw provider response or deserialized wire payload).
+          # from_hash({}) is a valid all-nil Usage (the no-usage object), never nil.
+          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(
+              input_tokens: hash[:input_tokens],
+              output_tokens: hash[:output_tokens],
+              cache_read_tokens: hash[:cache_read_tokens],
+              cache_write_tokens: hash[:cache_write_tokens],
+              thinking_tokens: hash[:thinking_tokens],
+              units: hash[:units] || {},
+              metadata:
+            )
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
@@ -75,8 +63,27 @@ module Legion
             [input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
              thinking_tokens].compact.sum
           end
+
+          # H1/M3: the single strict constructor. .new validates the token
+          # members as Integers (a string count would raise deep in
+          # StreamAccumulator#total_tokens instead of at construction) and
+          # units as a Hash. The factories fill their defaults and delegate
+          # here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:input_tokens] = Strict.expect_type!(values[:input_tokens], [::Integer], site, :input_tokens)
+            values[:output_tokens] = Strict.expect_type!(values[:output_tokens], [::Integer], site, :output_tokens)
+            values[:cache_read_tokens] = Strict.expect_type!(values[:cache_read_tokens], [::Integer], site, :cache_read_tokens)
+            values[:cache_write_tokens] = Strict.expect_type!(values[:cache_write_tokens], [::Integer], site, :cache_write_tokens)
+            values[:thinking_tokens] = Strict.expect_type!(values[:thinking_tokens], [::Integer], site, :thinking_tokens)
+            values[:units] = values[:units].nil? ? {} : Strict.expect_type!(values[:units], [::Hash], site, :units)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
         end
-        # rubocop:enable Lint/ConstantDefinitionInBlock
+
+        Usage::BUILD_SITE = 'Canonical::Usage.build'
+        Usage::FROM_HASH_SITE = 'Canonical::Usage.from_hash'
+        Usage::NEW_SITE = 'Canonical::Usage.new'
       end
     end
   end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'canonical/strict'
 require_relative 'canonical/thinking'
 require_relative 'canonical/usage'
 require_relative 'canonical/params'
@@ -26,17 +27,17 @@ module Legion
       module Canonical
         CONTRACT_VERSION = '1.0.0'
 
-        # Available canonical types.
+        # Available canonical types (the frozen 04 §1 inventory).
         TYPES = %i[
-          Thinking Usage Params ContentBlock
-          ToolDefinition ToolCall Message
-          Request Response Chunk
+          Message ContentBlock ToolCall ToolDefinition ToolSchema
+          Params Thinking Thinking::Config
+          Request Response Chunk Usage
         ].freeze
 
         class << self
           # List all canonical type classes.
           def types
-            TYPES.map { |name| const_get(name) }
+            TYPES.map { |name| name.to_s.split('::').reduce(self) { |mod, part| mod.const_get(part) } }
           end
 
           # Check if a given constant name is a registered canonical type.

data/lib/legion/extensions/llm/configuration.rb

@@ -26,23 +26,49 @@ module Legion
             Array(keys).each { |key| option(key.to_sym) }
           end
 
+          include Legion::Logging::Helper
+
+          # L5: the log defaults, read from the settings system (the ENV
+          # reads are deleted). A configured log_level Symbol/String names a
+          # Logger constant — an unknown name is a configuration error (it
+          # raises, it does not fall back).
+          def log_settings_defaults
+            {
+              level: log_level_value(llm_setting(:log_level)),
+              stream_debug: llm_setting(:log_stream_debug) == true
+            }
+          end
+
           private
 
           def option_keys = @option_keys ||= []
           def defaults = @defaults ||= {}
-          private :option
+
+          def log_level_value(value)
+            return Logger::INFO if value.nil?
+
+            value.is_a?(::Integer) ? value : Logger.const_get(value.to_s.upcase)
+          end
+
+          def llm_setting(key)
+            return nil unless defined?(::Legion::Settings) && ::Legion::Settings.respond_to?(:dig)
+
+            ::Legion::Settings.dig(:extensions, :llm, key)
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'llm.configuration.setting', key:)
+            nil
+          end
+          private :option, :log_level_value, :llm_setting
         end
 
         # System-level options are declared here.
         # Provider-specific options are declared in each provider extension via
         # `self.configuration_options`.
-        option :default_model, nil
-        option :default_embedding_model, nil
-        option :default_moderation_model, nil
-        option :default_image_model, nil
-        option :default_transcription_model, nil
-
-        option :model_registry_file, -> { File.expand_path('models.json', __dir__) }
+        # H4: the dormant default_model / default_*_model options are deleted —
+        # a model-defaulting authority with no consumer (verified in-repo and
+        # in consumer gems). Model selection belongs to the router.
+        # The model_registry_file option is deleted with the Models catalog
+        # (the second inventory) — the SSOT registry is the only inventory.
 
         option :request_timeout, 300
         option :max_retries, 3
@@ -53,8 +79,12 @@ module Legion
 
         option :logger, nil
         option :log_file, -> { $stdout }
-        option :log_level, -> { ENV['LEGION_LLM_DEBUG'] ? Logger::DEBUG : Logger::INFO }
-        option :log_stream_debug, -> { ENV['LEGION_LLM_STREAM_DEBUG'] == 'true' }
+        # L5: the ENV reads (LEGION_LLM_DEBUG / LEGION_LLM_STREAM_DEBUG) are
+        # deleted — every tunable lives in the settings system:
+        # extensions.llm.log_level (Symbol/Integer; Logger::INFO when unset)
+        # and extensions.llm.log_stream_debug (boolean; false when unset).
+        option :log_level, -> { self.class.log_settings_defaults[:level] }
+        option :log_stream_debug, -> { self.class.log_settings_defaults[:stream_debug] }
         option :log_regexp_timeout, -> { Regexp.respond_to?(:timeout) ? (Regexp.timeout || 1.0) : nil }
 
         # Prompt caching

data/lib/legion/extensions/llm/connection.rb

@@ -13,7 +13,7 @@ module Legion
           include Legion::Logging::Helper
 
           def basic(&)
-            logger = faraday_logger
+            logger = faraday_logger_for(Legion::Extensions::Llm.config, log)
             Faraday.new do |f|
               f.response :logger,
                          logger,
@@ -25,22 +25,20 @@ module Legion
               yield f if block_given?
             end
           end
+        end
 
-          private
-
-          def faraday_logger
-            config = Legion::Extensions::Llm.config
-            return config.logger if config.respond_to?(:logger) && config.logger
+        # One Faraday logger resolution (10 U9): the configured logger when
+        # present, else the caller's fallback log.
+        def self.faraday_logger_for(config_source, fallback_log)
+          return config_source.logger if config_source.respond_to?(:logger) && config_source.logger
 
-            log
-          end
+          fallback_log
         end
 
         def initialize(provider, config)
           @provider = provider
           @config = config
 
-          ensure_configured!
           @connection ||= Faraday.new(provider.api_base) do |faraday|
             faraday.ssl.verify = false
             setup_timeout(faraday)
@@ -83,7 +81,7 @@ module Legion
         end
 
         def setup_logging(faraday)
-          logger = faraday_logger
+          logger = self.class.faraday_logger_for(config, log)
           # Enable request body logging when the logger is at DEBUG level,
           # or when explicitly enabled via fleet request_payload setting.
           request_payload = Legion::Extensions::Llm.default_settings.dig(:fleet, :request, :logger, :request_payload)
@@ -100,12 +98,6 @@ module Legion
           end
         end
 
-        def faraday_logger
-          return config.logger if config.respond_to?(:logger) && config.logger
-
-          log
-        end
-
         def debug_logger?(logger)
           return logger.debug? if logger.respond_to?(:debug?)
           return logger.level.to_i <= Logger::DEBUG if logger.respond_to?(:level)
@@ -164,20 +156,6 @@ module Legion
             Legion::Extensions::Llm::OverloadedError
           ]
         end
-
-        def ensure_configured!
-          return if @provider.configured?
-
-          missing = @provider.configuration_requirements.reject { |req| @config.send(req) }
-          config_block = <<~RUBY
-            Legion::Extensions::Llm.configure do |config|
-              #{missing.map { |key| "config.#{key} = ENV['#{key.to_s.upcase}']" }.join("\n  ")}
-            end
-          RUBY
-
-          raise ConfigurationError,
-                "#{@provider.name} provider is not configured. Add this to your initialization:\n\n#{config_block}"
-        end
       end
     end
   end

data/lib/legion/extensions/llm/credential_sources.rb

@@ -58,8 +58,12 @@ module Legion
           env_hash[key.to_sym] || env_hash[key.to_s]
         end
 
+        # The codex auth file is an optional source: absent means "no codex
+        # credential" (probe semantics); present-but-unreadable raises from
+        # read_json (O11 fail-closed).
         def codex_token
           return nil unless credential_source_probing_enabled?
+          return nil unless File.exist?(CODEX_AUTH)
 
           data = read_json(CODEX_AUTH)
           mode = data[:auth_mode] || data['auth_mode']
@@ -74,6 +78,7 @@ module Legion
 
         def codex_openai_key
           return nil unless credential_source_probing_enabled?
+          return nil unless File.exist?(CODEX_AUTH)
 
           data = read_json(CODEX_AUTH)
           val = data[:OPENAI_API_KEY] || data['OPENAI_API_KEY']
@@ -198,19 +203,12 @@ module Legion
           credential_fingerprint(val)
         end
 
-        # Returns true when the URL points to localhost / 127.0.0.1 / ::1.
+        # Returns true when the URL points to localhost / 127.0.0.1 / ::1
+        # (the one shared host-locality detector — Utils.localhost_url?).
         def localhost?(url)
           return false if url.nil?
 
-          uri = URI.parse(url.to_s)
-          host = uri.host
-          return false if host.nil?
-
-          normalized = host.delete_prefix('[').delete_suffix(']')
-          %w[localhost 127.0.0.1 ::1].include?(normalized)
-        rescue URI::InvalidURIError => e
-          handle_exception(e, level: :warn, handled: true, operation: 'llm.credential_sources.localhost')
-          false
+          Utils.localhost_url?(url)
         end
 
         module_function :env, :credential_source_probing_enabled?,
@@ -224,69 +222,54 @@ module Legion
         # --- private helpers -----------------------------------------------
 
         # Merge user-level (~/.claude/settings.json) and project-level
-        # (.claude/settings.json) Claude configs.  Project overrides user.
+        # (.claude/settings.json) Claude configs.  Both files are optional
+        # sources: absent means "no config from that level".  Project overrides
+        # user.
         def merge_claude_configs
-          user = read_json(CLAUDE_SETTINGS)
-          project = read_json(CLAUDE_PROJECT)
-          deep_merge(user, project)
+          user = File.exist?(CLAUDE_SETTINGS) ? read_json(CLAUDE_SETTINGS) : {}
+          project = File.exist?(CLAUDE_PROJECT) ? read_json(CLAUDE_PROJECT) : {}
+          Utils.deep_merge(user, project)
         end
 
-        # Read and parse a JSON file.  Returns an empty hash on any error.
+        # Read and parse a JSON file.  O11 fail-closed: a missing, empty, or
+        # unreadable/unparseable credential file raises — it is a
+        # configuration error, never a fabricated empty credential.
         def read_json(path)
-          return {} unless File.exist?(path)
+          raise ConfigurationError, "credential file is missing: #{path}" unless File.exist?(path)
 
           raw = File.read(path)
-          return {} if raw.strip.empty?
+          raise ConfigurationError, "credential file is empty: #{path}" if raw.strip.empty?
 
-          if defined?(::Legion::JSON)
-            ::Legion::JSON.parse(raw, symbolize_names: true)
-          else
-            ::JSON.parse(raw, symbolize_names: true)
-          end
-        rescue StandardError => e
-          handle_exception(e, level: :warn, handled: true, operation: 'llm.credential_sources.read_json',
-                              path:)
-          {}
+          # L1: Legion::JSON only (house rule) — the bare ::JSON fallback is
+          # deleted; Legion::JSON is a hard dependency of this gem.
+          ::Legion::JSON.parse(raw, symbolize_names: true)
         end
 
         # JWT expiry check.  Decodes the base64 payload segment and checks
-        # that exp > now.  Returns true on any parse error (benefit of the
-        # doubt).
+        # that exp > now.  O11 fail-closed: unreadable or invalid token data
+        # is INVALID (the old benefit-of-the-doubt true is deleted). A
+        # parseable token with no exp claim has nothing to violate.
         def token_valid?(token)
-          return true if token.nil?
-
           require 'base64'
-          require 'json'
 
           parts = token.to_s.split('.')
-          return true unless parts.length >= 2
+          return false if parts.length < 2
 
-          payload = ::JSON.parse(Base64.urlsafe_decode64(parts[1]))
+          # L1: Legion::JSON only (string keys — the JWT payload is read by
+          # string key).
+          payload = ::Legion::JSON.parse(Base64.urlsafe_decode64(parts[1]), symbolize_names: false)
           exp = payload['exp']
           return true if exp.nil?
 
           exp.to_i > Time.now.to_i
         rescue StandardError => e
           handle_exception(e, level: :warn, handled: true, operation: 'llm.credential_sources.token_valid')
-          true
-        end
-
-        # Simple recursive hash merge (project values override user values).
-        def deep_merge(base, override)
-          base.merge(override) do |_key, old_val, new_val|
-            if old_val.is_a?(Hash) && new_val.is_a?(Hash)
-              deep_merge(old_val, new_val)
-            else
-              new_val
-            end
-          end
+          false
         end
 
-        module_function :merge_claude_configs, :read_json,
-                        :token_valid?, :deep_merge
+        module_function :merge_claude_configs, :read_json, :token_valid?
 
-        private_class_method :merge_claude_configs, :read_json,
-                             :token_valid?, :deep_merge
+        private_class_method :merge_claude_configs, :read_json, :token_valid?
       end
     end
   end