phronomy 0.16.0 → 0.17.0

data/lib/phronomy/agent/context/capability/base.rb

@@ -5,35 +5,8 @@ module Phronomy
     module Context
       module Capability
         # Base class extending RubyLLM::Tool with Phronomy-specific DSL.
-        #
-        # Additional DSL over RubyLLM::Tool:
-        #   - tool_name         : explicit function name exposed to the LLM (overrides auto-conversion)
-        #   - on_error          : error-handling policy (:raise or :return_empty)
-        #   - on_schema_error   : behavior when LLM passes schema-violating arguments
-        #                         :return_error (default), :raise, or :coerce
-        #   - requires_approval : Boolean/callable Tool-side approval default
-        #   - approval_facts    : callable exposing semantic facts to Agent policy
-        #   - param :name, enum: [...] : restrict allowed values in the JSON Schema
-        #
-        # @example
-        #   class SearchKnowledgeBase < Phronomy::Agent::Context::Capability::Base
-        #     tool_name "search_kb"               # explicit name shown to the LLM
-        #     description "Search the internal knowledge base"
-        #     param :query,  type: :string, desc: "Search query"
-        #     param :lang,   type: :string, desc: "Language", required: false, enum: %w[en ja fr]
-        #     on_error :return_empty
-        #
-        #     def execute(query:, lang: "en")
-        #       KnowledgeBase.search(query, lang: lang)
-        #     end
-        #   end
         class Base < RubyLLM::Tool
           class << self
-            # Sets an explicit function name to expose to the LLM, bypassing RubyLLM's
-            # automatic CamelCase-to-snake_case conversion.
-            # When omitted, RubyLLM's default conversion applies (e.g. WeatherTool → "weather").
-            #
-            # @param value [String, nil] the exact function name the LLM will see
             # @api public
             def tool_name(value = nil)
               return @tool_name if value.nil?
@@ -41,131 +14,153 @@ module Phronomy
               @tool_name = value.to_s
             end
 
-            # Extends RubyLLM::Tool.param with optional +enum:+ and +properties:+ keywords.
-            # - +enum:+       restricts allowed values; injected into the JSON Schema.
-            # - +properties:+ declares nested fields for :object type params.  Each
-            #   entry is a Hash mapping field name (Symbol) to a spec Hash with keys:
-            #   :type (Symbol, default :string), :required (Boolean, default false),
-            #   and optionally :properties (for further nesting).
-            #
-            # @param name [Symbol] parameter name
-            # @param enum [Array, nil] allowed values
-            # @param properties [Hash, nil] nested schema for :object params
-            # @param options [Hash] forwarded to RubyLLM::Tool.param
+            # RubyLLM stores Tool descriptions in a class-instance variable.
+            # Preserve normal class inheritance semantics so Phronomy's anonymous
+            # decorator subclasses do not lose their parent's description.
+            # @api public
+            def description(text = nil)
+              unless text
+                return @description if instance_variable_defined?(:@description)
+                return superclass.description if superclass.respond_to?(:description)
+
+                return nil
+              end
+
+              @description = text
+            end
+            alias_method :desc, :description
+
+            # RubyLLM stores declared parameters in a class-instance variable.
+            # Copy the parent's registry on first access so child classes inherit
+            # existing parameters while remaining free to add their own.
+            # @api public
+            def parameters
+              return @parameters if instance_variable_defined?(:@parameters)
+
+              parent = superclass.respond_to?(:parameters) ? superclass.parameters : {}
+              @parameters = parent.dup
+            end
+
+            # RubyLLM stores an explicit .params schema definition in a
+            # class-instance variable. Readers must fall back to the parent.
+            # @api public
+            def params_schema_definition
+              return @params_schema_definition if instance_variable_defined?(:@params_schema_definition)
+              return superclass.params_schema_definition if superclass.respond_to?(:params_schema_definition)
+
+              nil
+            end
+
+            # RubyLLM provider params are also class-instance state. Copy them on
+            # first access to preserve inheritance without sharing the top-level
+            # mutable Hash between parent and child.
+            # @api public
+            def provider_params
+              return @provider_params if instance_variable_defined?(:@provider_params)
+
+              parent = superclass.respond_to?(:provider_params) ? superclass.provider_params : {}
+              @provider_params = duplicate_configuration(parent)
+            end
+
             # @api public
             def param(name, enum: nil, properties: nil, **options)
               super(name, **options)
-              param_enums[name] = enum if enum
+              param_enums[name] = duplicate_configuration(enum) if enum
               param_schemas[name] = normalize_nested_schema(properties) if properties
             end
 
-            # Returns the enum constraints registered via .param.
-            # @return [Hash{Symbol => Array}]
             # @api public
             def param_enums
-              @param_enums ||= {}
+              return @param_enums if instance_variable_defined?(:@param_enums)
+
+              parent = superclass.respond_to?(:param_enums) ? superclass.param_enums : {}
+              @param_enums = duplicate_configuration(parent)
             end
 
-            # Returns nested schema definitions registered via .param(properties: ...).
-            # @return [Hash{Symbol => Hash}]
             # @api public
-            # mutant:disable - neutral failure: unparser round-trip produces different source
             def param_schemas
-              @param_schemas ||= {}
+              return @param_schemas if instance_variable_defined?(:@param_schemas)
+
+              parent = superclass.respond_to?(:param_schemas) ? superclass.param_schemas : {}
+              @param_schemas = duplicate_configuration(parent)
             end
 
             private
 
-            # Recursively normalises a properties hash so all keys are Symbols and
-            # each spec has a :type key.
-            # mutant:disable
+            def duplicate_configuration(value)
+              case value
+              when Hash
+                value.to_h do |key, child|
+                  [key, duplicate_configuration(child)]
+                end
+              when Array
+                value.map { |child| duplicate_configuration(child) }
+              else
+                value
+              end
+            end
+
             def normalize_nested_schema(props)
               props.transform_keys(&:to_sym).transform_values do |spec|
-                s = spec.transform_keys(&:to_sym)
-                s[:type] ||= :string
-                s[:properties] = normalize_nested_schema(s[:properties]) if s[:properties]
-                s
+                normalized = spec.transform_keys(&:to_sym)
+                normalized[:type] ||= :string
+                if normalized[:properties]
+                  normalized[:properties] = normalize_nested_schema(normalized[:properties])
+                end
+                normalized
               end
             end
 
             public
 
-            # Sets or reads the execution mode for this tool.
-            #
-            # Execution mode is the concurrency contract declaration for the tool.
-            # In Phronomy's non-preemptive, cooperative concurrency model it controls
-            # which runtime resource is used to dispatch the tool:
-            #
-            # | Mode | Dispatcher | Constraint |
-            # |------|-----------|------------|
-            # | +:cooperative+ | +Runtime.instance.spawn+ (scheduler task) | *Must not* block the scheduler thread; use only for in-memory computation |
-            # | +:blocking_io+ | {Phronomy::Concurrency::BlockingAdapterPool} (bounded thread pool) | **Default**. Safe for all blocking I/O (HTTP, DB, file) |
-            # | +:cpu_bound+ | Falls back to +:blocking_io+ + emits a warning | No dedicated process pool yet; use +:blocking_io+ explicitly to suppress the warning |
-            # | +:external_process+ | Falls back to +:blocking_io+ | No process manager yet |
-            #
-            # Tools that perform network calls, file I/O, or database queries should use
-            # +:blocking_io+ (the default).  Tools that only perform in-memory computation
-            # may declare +:cooperative+ for lower overhead.
-            #
-            # @param value [Symbol, nil] when nil, returns the current value
-            # @return [Symbol] the current execution mode (default :blocking_io)
             # @api public
-            # mutant:disable
             def execution_mode(value = nil)
-              return @execution_mode || :blocking_io if value.nil?
+              if value.nil?
+                return @execution_mode if instance_variable_defined?(:@execution_mode)
+                return superclass.execution_mode if superclass.respond_to?(:execution_mode)
+
+                return :blocking_io
+              end
 
               valid = %i[cooperative blocking_io cpu_bound external_process]
               unless valid.include?(value)
-                raise ArgumentError, "execution_mode must be one of #{valid.inspect}, got #{value.inspect}"
+                raise ArgumentError,
+                  "execution_mode must be one of #{valid.inspect}, got #{value.inspect}"
               end
-
               @execution_mode = value
             end
 
-            # Configures error-handling behavior when +execute+ raises an unexpected error.
-            #
-            # @param behavior [Symbol]
-            #   :raise        (default)  — re-raise as Phronomy::ToolError, stopping the agent.
-            #   :suppress                — suppress the error and return a descriptive string so
-            #                             the LLM can recover on the next turn.
-            #   :return_empty            — *deprecated* alias for +:suppress+; will be removed in a
-            #                             future major release.
+            # Configures execution-error handling. Supported values are :raise
+            # and :suppress only.
             # @api public
             def on_error(behavior = nil)
-              return @on_error || :raise if behavior.nil?
+              if behavior.nil?
+                return @on_error if instance_variable_defined?(:@on_error)
+                return superclass.on_error if superclass.respond_to?(:on_error)
 
-              if behavior == :return_empty
-                msg = "[Phronomy] on_error :return_empty is deprecated; use :suppress instead"
-                if Phronomy.configuration.logger
-                  Phronomy.configuration.logger.warn(msg)
-                else
-                  warn msg
-                end
+                return :raise
+              end
+
+              valid = %i[raise suppress]
+              unless valid.include?(behavior)
+                raise ArgumentError,
+                  "on_error must be one of #{valid.inspect}, got #{behavior.inspect}"
               end
               @on_error = behavior
             end
 
-            # Configures how this tool responds when the LLM passes arguments that violate
-            # the declared parameter types or enum constraints.
-            #
-            # @param behavior [Symbol]
-            #   :return_error (default) — return a descriptive error string as the tool result
-            #                             so the LLM can self-correct on the next turn.
-            #   :raise                  — raise Phronomy::ToolError, stopping the agent loop.
-            #   :coerce                 — attempt type coercion (e.g. "42" → 42 for :integer);
-            #                             falls back to :return_error when coercion is not possible.
             # @api public
-            # mutant:disable - neutral failure: unparser round-trip produces different source
             def on_schema_error(behavior = nil)
-              return @on_schema_error || :return_error if behavior.nil?
+              if behavior.nil?
+                return @on_schema_error if instance_variable_defined?(:@on_schema_error)
+                return superclass.on_schema_error if superclass.respond_to?(:on_schema_error)
+
+                return :return_error
+              end
 
               @on_schema_error = behavior
             end
 
-            # Configures the Tool-side default for approval. A callable receives
-            # ApprovalEvaluationRequest and must return true or false. It is
-            # evaluated on the Runtime authorization pool, not in Tool#call.
-            # @param value [Boolean, #call]
             # @api public
             def requires_approval(value = :__unset__, &block)
               if block
@@ -186,8 +181,6 @@ module Phronomy
               end
             end
 
-            # Registers a Tool-specific semantic fact extractor for authorization.
-            # The block receives validated immutable arguments and read-only context.
             # @api public
             def approval_facts(&block)
               if block
@@ -199,13 +192,7 @@ module Phronomy
               end
             end
 
-            # Marks one or more parameter names as sensitive so their values are
-            # replaced with +"[REDACTED]"+ in log and trace output.
-            #
-            # @param names [Array<Symbol>] parameter names to redact
-            # @return [Array<Symbol>] the full list of redacted param names
             # @api public
-            # mutant:disable
             def redact_params(*names)
               if names.empty?
                 parent = superclass.respond_to?(:redact_params) ? superclass.redact_params : []
@@ -215,34 +202,23 @@ module Phronomy
               end
             end
 
-            # Sets a per-tool maximum result size (in characters).
-            # Overrides the global +Phronomy.configuration.tool_result_max_size+ when set.
-            # Set to +nil+ to inherit the global limit.
-            #
-            # @param value [Integer, nil]
             # @api public
             def max_result_size(value = :__unset__)
-              return @max_result_size if value == :__unset__
+              if value == :__unset__
+                return @max_result_size if instance_variable_defined?(:@max_result_size)
+                return superclass.max_result_size if superclass.respond_to?(:max_result_size)
+
+                return nil
+              end
 
               @max_result_size = value
             end
           end
 
-          # Returns the function name exposed to the LLM.
-          # Uses the class-level tool_name if set; otherwise falls back to RubyLLM's
-          # automatic conversion (CamelCase → snake_case, strips trailing "_tool").
-          # mutant:disable - neutral failure: unparser round-trip produces different source
           def name
             self.class.tool_name || super
           end
 
-          # Returns the JSON Schema for this tool's parameters.
-          # Injects "enum" entries for any param declared with enum: [...].
-          # mutant:disable - genuine equivalent mutations:
-          #   1. `|| schema.dig(:properties)`: dead code because RubyLLM::Tool always returns a
-          #      string-keyed hash; schema.dig(:properties) is always nil in practice.
-          #   2. `return schema unless properties` guard: dead code when schema is non-nil because
-          #      RubyLLM::Tool always includes a "properties" key when parameters are declared.
           def params_schema
             schema = super
             return schema if schema.nil?
@@ -250,103 +226,76 @@ module Phronomy
             properties = schema.dig("properties") || schema.dig(:properties)
             return schema unless properties
 
-            # Inject enum values for params declared with enum: [...].
-            unless self.class.param_enums.empty?
-              enums = self.class.param_enums
-              enums.each do |param_name, values|
-                key = properties.key?(param_name.to_s) ? param_name.to_s : param_name.to_sym
-                next unless properties[key]
-
-                param_type = properties[key]["type"]
-                properties[key]["enum"] = values.map do |v|
-                  case param_type
-                  when "integer" then v.is_a?(Integer) ? v : Integer(v.to_s)
-                  when "number" then v.is_a?(Numeric) ? v : Float(v.to_s)
-                  when "boolean"
-                    unless v == true || v == false
-                      raise ArgumentError,
-                        "boolean enum values must be true or false (got: #{v.inspect})"
-                    end
-                    v
-                  else v.to_s
+            self.class.param_enums.each do |param_name, values|
+              key = properties.key?(param_name.to_s) ? param_name.to_s : param_name.to_sym
+              next unless properties[key]
+
+              param_type = properties[key]["type"]
+              properties[key]["enum"] = values.map do |value|
+                case param_type
+                when "integer"
+                  value.is_a?(Integer) ? value : Integer(value.to_s)
+                when "number"
+                  value.is_a?(Numeric) ? value : Float(value.to_s)
+                when "boolean"
+                  unless value == true || value == false
+                    raise ArgumentError,
+                      "boolean enum values must be true or false (got: #{value.inspect})"
                   end
+                  value
+                else
+                  value.to_s
                 end
               end
             end
 
-            # Inject nested properties for :object params (issue #162).
-            # Without this the LLM sees only { "type": "object" } with no field
-            # definitions, making it unable to populate nested object params.
             self.class.param_schemas.each do |param_name, nested|
               key = properties.key?(param_name.to_s) ? param_name.to_s : param_name.to_sym
               next unless properties[key]
-
               properties[key]["properties"] = nested_schema_to_json_schema(nested)
             end
 
             schema
           end
 
-          # Overrides RubyLLM::Tool#call to apply schema validation,
-          # the on_error policy, and wrap errors as ToolError.
-          #
-          # Execution order:
-          #   1. Early cancellation check (kwarg token takes precedence over thread-local).
-          #   2. Schema validation (type + enum checks).
-          #   3. Inject +cancellation_token:+ into args when +execute+ opts in.
-          #   4. Call super(validated_args) exactly once.
-          #   5. On failure, apply on_error policy.
-          #
-          # @param args               [Hash]
-          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; takes precedence over the thread-local token
           # @api public
-          # mutant:disable
           def call(args, cancellation_token: nil)
-            ct = cancellation_token
-            ct&.raise_if_cancelled!
+            cancellation_token&.raise_if_cancelled!
             validated_args, schema_error = validate_and_coerce(args)
             if schema_error
               case self.class.on_schema_error
               when :raise
-                raise Phronomy::ToolError, "#{self.class.name} schema error: #{schema_error}"
+                raise Phronomy::ToolError,
+                  "#{self.class.name} schema error: #{schema_error}"
               else
-                # :return_error (default) and coerce fallback
                 return "Schema validation failed: #{schema_error}"
               end
             end
-            validated_args = validated_args.merge(cancellation_token: ct) if ct && execute_accepts_cancellation_token?
+
+            if cancellation_token && execute_accepts_cancellation_token?
+              validated_args = validated_args.merge(cancellation_token: cancellation_token)
+            end
             result = super(validated_args)
             truncate_result_if_needed(result)
-          rescue Phronomy::ToolError
-            raise
-          rescue Phronomy::CancellationError
+          rescue Phronomy::ToolError, Phronomy::CancellationError
             raise
-          rescue => e
-            case self.class.on_error
-            when :return_empty, :suppress
-              msg = "[Phronomy] Tool #{self.class.name} suppressed error: #{e.class}: #{e.message}"
+          rescue => error
+            if self.class.on_error == :suppress
+              msg = "[Phronomy] Tool #{self.class.name} suppressed error: " \
+                "#{error.class}: #{error.message}"
               if Phronomy.configuration.logger
                 Phronomy.configuration.logger.warn(msg)
               else
                 warn msg
               end
-              "Tool error suppressed: #{e.message}"
+              "Tool error suppressed: #{error.message}"
             else
-              raise Phronomy::ToolError, "#{self.class.name} execution failed: #{e.message}"
+              raise Phronomy::ToolError,
+                "#{self.class.name} execution failed: #{error.message}"
             end
           end
 
-          # Invokes this tool asynchronously and returns a {Phronomy::Task}.
-          #
-          # Routing is governed by the class-level {.execution_mode} setting.
-          # Delegates to {Phronomy::Agent::ToolExecutor.call_async} which is the single
-          # place in the framework that applies the execution-mode routing rules.
-          #
-          # @param args               [Hash]
-          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-          # @return [#await]
           # @api public
-          # mutant:disable
           def call_async(args, cancellation_token: nil, config: {})
             Phronomy::Agent::ToolExecutor.call_async(
               tool: self,
@@ -356,47 +305,24 @@ module Phronomy
             )
           end
 
-          # Instance method accessor — delegates to the class-level flag.
           def requires_approval
             self.class.requires_approval
           end
 
-          # Instance method for requires_approval? (convenience accessor).
-          # mutant:disable - genuine equivalent: self.requires_approval delegates to
-          # self.class.requires_approval via the instance method defined above, so
-          # both expressions produce the same value.
           def requires_approval?
             self.class.requires_approval
           end
 
-          # Origin metadata consumed by ToolInvocation authorization policy.
           # @api public
           def tool_origin
             :local
           end
 
-          # Display-safe transport/origin metadata for approval requests.
           # @api public
           def approval_metadata
             {}
           end
 
-          # Override this method to implement the tool's logic.
-          #
-          # The method receives the declared {.param} fields as keyword arguments.
-          # The return value is passed back to the LLM as the tool result.
-          #
-          # @abstract Subclasses must implement this method.
-          # @return [String] result string returned to the LLM
-          # @example
-          #   class WeatherTool < Phronomy::Agent::Context::Capability::Base
-          #     description "Get current weather"
-          #     param :location, type: :string, desc: "City name"
-          #
-          #     def execute(location:)
-          #       WeatherService.fetch(location).to_s
-          #     end
-          #   end
           # @api public
           def execute(**_args)
             raise NotImplementedError, "#{self.class}#execute is not implemented"
@@ -404,24 +330,18 @@ module Phronomy
 
           private
 
-          # Returns true when the #execute method declares a +cancellation_token:+
-          # keyword parameter, indicating it opts into cooperative cancellation.
-          # mutant:disable
           def execute_accepts_cancellation_token?
-            method(:execute).parameters.any? do |type, name| # mutant:disable
+            method(:execute).parameters.any? do |type, name|
               name == :cancellation_token && %i[key keyreq].include?(type)
             end
           end
 
-          # Truncates the result string when it exceeds the configured maximum size.
-          # Uses the per-tool limit first, then the global configuration limit.
-          # Returns the original result when no limit is configured.
           def truncate_result_if_needed(result)
             max = self.class.max_result_size || Phronomy.configuration.tool_result_max_size
             return result unless max && result.respond_to?(:length) && result.length > max
 
             msg = "[Phronomy] Tool #{self.class.name} result truncated " \
-                  "(#{result.length} chars > #{max} limit)"
+              "(#{result.length} chars > #{max} limit)"
             if Phronomy.configuration.logger
               Phronomy.configuration.logger.warn(msg)
             else
@@ -430,45 +350,25 @@ module Phronomy
             "#{result[0, max]}...[truncated]"
           end
 
-          # Returns a copy of +args+ with redacted parameter values replaced by
-          # +"[REDACTED]"+.  Used for logging and tracing.
-          # @param args [Hash]
-          # @return [Hash]
-          # @api private
           def redacted_args(args)
             redacted = self.class.redact_params
             return args if redacted.empty?
 
-            args.each_with_object({}) do |(k, v), h|
-              h[k] = redacted.include?(k.to_sym) ? "[REDACTED]" : v
+            args.each_with_object({}) do |(key, value), result|
+              result[key] = redacted.include?(key.to_sym) ? "[REDACTED]" : value
             end
           end
 
-          # Validates args against declared parameter types and enum constraints.
-          # When on_schema_error is :coerce, attempts type coercion first.
-          #
-          # @param args [Hash] raw args passed to #call (string or symbol keys)
-          # @return [Array(Hash, String|nil)] [possibly_coerced_args, error_message_or_nil]
-          # @api public
-          # mutant:disable
           def validate_and_coerce(args)
-            # mutant:disable - genuine equivalents:
-            #   1. `return [args, nil]` vs `return [args]`: Ruby multiple assignment
-            #      fills nil for missing elements, so both are identical to callers.
-            #   2. `self.class.parameters` vs `self.parameters`: RubyLLM::Tool exposes
-            #      `parameters` as both a class method and an instance method that
-            #      delegates to the class method, so both return the same value.
             return [args, nil] if self.class.parameters.empty?
 
             normalized = (args || {}).transform_keys(&:to_sym)
             coerce_mode = self.class.on_schema_error == :coerce
             result = {}
 
-            self.class.parameters.each do |name, param| # mutant:disable
+            self.class.parameters.each do |name, param|
               value = normalized[name]
               if value.nil?
-                # Return a descriptive error for missing required params so the LLM
-                # can self-correct on the next turn.
                 return [nil, "required parameter '#{name}' is missing"] if param.required
                 next
               end
@@ -482,7 +382,6 @@ module Phronomy
                 return [nil, error] if error
               end
 
-              # Recursively validate nested object properties when declared.
               if param.type.to_sym == :object
                 nested_schema = self.class.param_schemas[name]
                 if nested_schema
@@ -493,62 +392,46 @@ module Phronomy
 
               enum_vals = self.class.param_enums[name]
               if enum_vals && !enum_vals.map(&:to_s).include?(value.to_s)
-                return [nil, "parameter '#{name}' must be one of: #{enum_vals.join(", ")} (got: #{value.inspect})"]
+                return [nil,
+                  "parameter '#{name}' must be one of: #{enum_vals.join(", ")} " \
+                  "(got: #{value.inspect})"]
               end
 
               result[name] = value
             end
 
-            # Reject any keys not covered by declared parameters to prevent silent
-            # parameter injection (e.g. via prompt injection).
-            extra = normalized.keys - self.class.parameters.keys # mutant:disable
+            extra = normalized.keys - self.class.parameters.keys
             unless extra.empty?
               return [nil, "unknown parameter(s): #{extra.inspect}"]
             end
 
-            [result, nil] # mutant:disable
+            [result, nil]
           end
 
-          # Converts the internal normalized nested schema (from param_schemas) to
-          # a JSON Schema +properties+ hash suitable for inclusion in the LLM tool
-          # definition (issue #162).
-          #
-          # @param nested [Hash{Symbol=>Hash}] normalized schema from param_schemas
-          # @return [Hash{String=>Hash}] JSON Schema properties
-          # @api public
-          # mutant:disable
           def nested_schema_to_json_schema(nested)
-            nested.each_with_object({}) do |(prop_name, spec), acc|
+            nested.each_with_object({}) do |(prop_name, spec), result|
               entry = {"type" => spec[:type].to_s}
               entry["description"] = spec[:desc] if spec[:desc]
               entry["enum"] = spec[:enum] if spec[:enum]
-              entry["properties"] = nested_schema_to_json_schema(spec[:properties]) if spec[:properties]
-              acc[prop_name.to_s] = entry
+              if spec[:properties]
+                entry["properties"] = nested_schema_to_json_schema(spec[:properties])
+              end
+              result[prop_name.to_s] = entry
             end
           end
 
-          # Recursively validates +value+ (a Hash) against a +properties+ schema.
-          # Returns an error message string or nil.
-          #
-          # @param value      [Hash]            the object value to validate
-          # @param properties [Hash{Symbol=>Hash}] nested schema from param_schemas
-          # @param path       [String]          dot-separated field path for error messages
-          # @api public
-          # mutant:disable
           def validate_nested_object(value, properties, path)
             return "field '#{path}' must be an object (Hash)" unless value.is_a?(Hash)
 
             normalized = value.transform_keys(&:to_sym)
-
-            # Reject extra keys not declared in the schema (issue #166).
             extra = normalized.keys - properties.keys
             unless extra.empty?
               return "nested field '#{path}' contains undeclared key(s): #{extra.inspect}"
             end
 
-            properties.each do |fname, spec|
-              field_path = "#{path}.#{fname}"
-              field_value = normalized[fname]
+            properties.each do |name, spec|
+              field_path = "#{path}.#{name}"
+              field_value = normalized[name]
 
               if field_value.nil?
                 return "nested required field '#{field_path}' is missing" if spec[:required]
@@ -566,13 +449,6 @@ module Phronomy
             nil
           end
 
-          # Returns a type-error message string if +value+ does not match +declared_type+,
-          # or nil if the value is acceptable.
-          #
-          # @param value         [Object]
-          # @param declared_type [Symbol, String]  e.g. :string, :integer, :number, :boolean, :array, :object
-          # @api public
-          # mutant:disable
           def type_error(value, declared_type)
             return nil if value.nil?
 
@@ -583,19 +459,15 @@ module Phronomy
             when :boolean then [true, false].include?(value)
             when :array then value.is_a?(Array)
             when :object then value.is_a?(Hash)
-            else true # unknown types pass through
+            else true
             end
 
-            if ok
-              nil
-            else
-              "parameter '#{value.respond_to?(:keys) ? "(object)" : value.inspect}' expected type #{declared_type}"
-            end
+            return nil if ok
+
+            shown = value.respond_to?(:keys) ? "(object)" : value.inspect
+            "parameter '#{shown}' expected type #{declared_type}"
           end
 
-          # Attempts to coerce +value+ to +declared_type+.
-          # Returns [coerced_value, nil] on success, [nil, error_message] on failure.
-          # mutant:disable
           def coerce_value(value, declared_type)
             return [value, nil] if value.nil?
 
@@ -603,11 +475,9 @@ module Phronomy
             when :string
               [value.to_s, nil]
             when :integer
-              coerced = Integer(value)
-              [coerced, nil]
+              [Integer(value), nil]
             when :number, :float
-              coerced = Float(value)
-              [coerced, nil]
+              [Float(value), nil]
             when :boolean
               case value.to_s.downcase
               when "true" then [true, nil]
@@ -615,7 +485,6 @@ module Phronomy
               else [nil, "parameter cannot be coerced to boolean: #{value.inspect}"]
               end
             else
-              # Arrays, objects, unknown types: pass through as-is
               [value, nil]
             end
           rescue ArgumentError, TypeError