squishling 0.2.0 → 0.3.0

data/lib/squishling/class_methods.rb

@@ -6,27 +6,49 @@ module Squishling
     DEFAULT_METHOD = :call
 
     # Set class-wide options in one call:
-    #   squishling model: "claude-sonnet-5-5", instructions: "...", output_schema: MySchema
+    #   squishling model: "claude-sonnet-5-5", purpose: "...", output_schema: MySchema
     # model: is a single attempt; escalation: is a list of models tried in order (see ModelPath):
     #   squishling escalation: [{ model: "claude-haiku-4-5", attempts: 2 }, "claude-sonnet-5-5", "claude-opus-5-5"]
     # Pass provider: alongside model: for models missing from RubyLLM's registry, e.g.
-    #   squishling model: "gpt-6-luna", provider: :openai
+    #   squishling model: "gpt-7-preview", provider: :openai
+    # provider: needs a model: or escalation: (declared on the class), and a subclass's model never inherits its
+    # parent's provider.
     # params: are generation params merged over the configured defaults (see Configuration#default_params):
     #   squishling params: { temperature: 0.1, top_p: 0.9 }
-    # append_instructions: adds sections after the instructions (see #append_instructions):
-    #   squishling append_instructions: ["The Ruby that handles well-formed input:", self]
-    def squishling(model: nil, escalation: nil, provider: nil, params: nil, instructions: nil,
-      append_instructions: nil, output_schema: nil)
+    # append_to_purpose: adds sections after the purpose (see #append_to_purpose):
+    #   squishling append_to_purpose: ["The Ruby that handles well-formed input:", self]
+    # harness: chooses how the escalation is used (see Harness):
+    #   squishling harness: :judged_squishsum
+    # squawk: is called after every LLM attempt with the raw output (see Configuration#squawk); false silences
+    # an inherited one:
+    #   squishling squawk: ->(output:, metadata:, error:) { Tracer.record(output, metadata, error) }
+    def squishling(model: nil, escalation: nil, provider: nil, params: nil, harness: nil, purpose: nil,
+      append_to_purpose: nil, output_schema: nil, squawk: nil)
       path = ModelPath.declare(model, escalation, to_s)
+      # A provider belongs to the model declared at the same level. Without a model here it would apply to
+      # nothing (the model comes from the config or a parent class), so it is an error unless this class already
+      # declared its own.
+      if provider && !path && !instance_variable_defined?(:@squishling_model_path)
+        raise ConfigurationError, "#{self}: provider: needs a model: or escalation: declared on this class"
+      end
+
+      # Stored (even as nil) whenever a model is, so a subclass that declares its own model never inherits a
+      # provider meant for its parent's.
       @squishling_model_path = path if path
-      @squishling_provider = provider if provider
+      @squishling_provider = provider if provider || path
       @squishling_params = Params.normalize(params, "#{self} params") if params
-      self.instructions(instructions) if instructions
-      self.append_instructions(append_instructions) unless append_instructions.nil?
+      @squishling_harness = Harness.normalize(harness, to_s) unless harness.nil?
+      self.purpose(purpose) if purpose
+      self.append_to_purpose(append_to_purpose) unless append_to_purpose.nil?
       self.output_schema(output_schema) if output_schema
+      @squishling_squawk = Squawk.validate(squawk, to_s) unless squawk.nil?
       self
     end
 
+    def squishling_squawk
+      squishling_lookup(:@squishling_squawk)
+    end
+
     # The class's (or nearest ancestor's) model or escalation, as normalized steps.
     def squishling_model_path
       squishling_lookup(:@squishling_model_path)
@@ -36,33 +58,37 @@ module Squishling
       squishling_lookup(:@squishling_provider)
     end
 
+    def squishling_harness
+      squishling_lookup(:@squishling_harness)
+    end
+
     # Generation params merged down the inheritance chain, so a subclass overrides individual keys.
     def squishling_params
       squishling_inherited(:squishling_params, {}).merge(@squishling_params || {})
     end
 
     # The system prompt. A String, or a Proc evaluated against the instance.
-    def instructions(text = nil, &block)
-      return squishling_lookup(:@squishling_instructions) if text.nil? && block.nil?
+    def purpose(text = nil, &block)
+      return squishling_lookup(:@squishling_purpose) if text.nil? && block.nil?
 
-      @squishling_instructions = block || text
+      @squishling_purpose = block || text
     end
 
-    # Sections appended to the system prompt after the instructions, added to by subclasses, `squish`, and
+    # Sections appended to the system prompt after the purpose, added to by subclasses, `squish`, and
     # `squish!`. Items: Strings; a class or module (`self` for this class) or a method (`instance_method(:call)`),
     # sent as its Ruby source; or a Proc evaluated against the instance. `false` drops inherited items.
-    #   append_instructions "Here is the Ruby that parses well-formed invoices:", self
-    #   append_instructions { "This client's invoices are in #{currency}." }
-    def append_instructions(*items, &block)
+    #   append_to_purpose "Here is the Ruby that parses well-formed invoices:", self
+    #   append_to_purpose { "This client's invoices are in #{currency}." }
+    def append_to_purpose(*items, &block)
       items = items.first if items.size == 1 && items.first.is_a?(Array)
       items += [block] if block
-      (@squishling_append_instructions ||= []).concat(Appendices.normalize(items, "#{self} append_instructions"))
+      (@squishling_append_to_purpose ||= []).concat(Appendices.normalize(items, "#{self} append_to_purpose"))
       self
     end
 
     # Every level's items in declaration order, `false` markers included (see Appendices.resolve).
-    def squishling_append_instructions
-      squishling_inherited(:squishling_append_instructions, []) + (@squishling_append_instructions || [])
+    def squishling_append_to_purpose
+      squishling_inherited(:squishling_append_to_purpose, []) + (@squishling_append_to_purpose || [])
     end
 
     # The output format: a Schematist::Schema subclass (RubyLLM::Schema with the ruby_llm-schema shim),
@@ -85,7 +111,7 @@ module Squishling
 
     # Called with the error and the method's inputs (as keywords) when the LLM path fails with an
     # InvalidOutputError or LLMError, evaluated against the instance. Its return value is used as
-    # the result (hashes are validated and typed); re-raise to propagate.
+    # the result (validated against the schema and typed like a deterministic return); re-raise to propagate.
     #   squish_fallback { |error, **inputs| { priority: "medium", team: "support" } }
     def squish_fallback(&block)
       @squishling_fallback = block
@@ -118,21 +144,26 @@ module Squishling
     end
 
     # Make methods elastic. Each may override the class-level settings:
-    #   squish :triage, instructions: "...", escalation: %w[claude-haiku-4-5 claude-sonnet-5-5], when: ->(**) { true },
-    #                   fallback: ->(error, **) { { priority: "medium" } }, append_instructions: [...],
-    #                   validate: ->(result, **) { "team is required" if result.team.empty? } do
+    #   squish :triage, purpose: "...", escalation: %w[claude-haiku-4-5 claude-sonnet-5-5], when: ->(**) { true },
+    #                   fallback: ->(error, **) { { priority: "medium" } }, append_to_purpose: [...],
+    #                   validate: ->(result, **) { "team is required" if result.team.empty? },
+    #                   harness: :squishsum, squawk: ->(output:, error:, **) { Tracer.record(output, error) } do
     #     string :priority
     #   end
-    def squish(*names, instructions: nil, append_instructions: nil, output_schema: nil, model: nil, escalation: nil,
-      provider: nil, params: nil, when: nil, fallback: nil, validate: nil, &schema_block)
+    def squish(*names, purpose: nil, append_to_purpose: nil, output_schema: nil, model: nil, escalation: nil,
+      provider: nil, params: nil, harness: nil, when: nil, fallback: nil, validate: nil, squawk: nil, &schema_block)
       schema = schema_block ? Schematist::Schema.create(&schema_block) : output_schema
       model = ModelPath.declare(model, escalation, "#{self} squish")
+      raise ConfigurationError, "#{self} squish: provider: needs a model: or escalation:" if provider && !model
+
       params &&= Params.normalize(params, "#{self} squish params")
-      unless append_instructions.nil?
-        append_instructions = Appendices.normalize(append_instructions, "#{self} squish append_instructions")
+      harness = Harness.normalize(harness, "#{self} squish") unless harness.nil?
+      unless append_to_purpose.nil?
+        append_to_purpose = Appendices.normalize(append_to_purpose, "#{self} squish append_to_purpose")
       end
-      options = { instructions:, append_instructions:, output_schema: schema, model:, provider:, params:,
-                  predicate: binding.local_variable_get(:when), fallback:, validator: validate }.compact
+      squawk = Squawk.validate(squawk, "#{self} squish")
+      options = { purpose:, append_to_purpose:, output_schema: schema, model:, provider:, params:, harness:,
+                  predicate: binding.local_variable_get(:when), fallback:, validator: validate, squawk: }.compact
 
       names.map(&:to_sym).each do |name|
         (@squishling_methods ||= {})[name] = options

data/lib/squishling/collisions.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Squishling
+  # `include Squishling` puts its methods ahead of inherited ones, so a class that inherits a method of the same
+  # name (Sinatra::Base.call, a parent's own `purpose`, ...) would be silently shadowed. Methods the class
+  # defines itself always win, so they are never reported.
+  module Collisions
+    INSTANCE_METHODS = %i[squish! squishling_result].freeze
+
+    module_function
+
+    # Raises ConfigurationError naming every inherited method Squishling would override. Call it before
+    # extending the class with ClassMethods, and after the module is in the class's ancestors.
+    def check!(base)
+      found = class_collisions(base) + instance_collisions(base)
+      return if found.empty?
+
+      raise ConfigurationError,
+        "#{base} inherits methods that Squishling would override: #{found.join(', ')}. " \
+        "Include Squishling in a plain Ruby class instead (compose the framework object rather than inheriting it)"
+    end
+
+    def class_collisions(base)
+      ClassMethods.public_instance_methods(false).filter_map do |name|
+        next if name == :inherited || !base.respond_to?(name, true)
+
+        owner = base.method(name).owner
+        next if owner == base.singleton_class || owner == ClassMethods
+
+        "#{base}.#{name} (from #{describe(owner)})"
+      end
+    end
+
+    def instance_collisions(base)
+      ancestors = base.ancestors
+      inherited = ancestors.drop(ancestors.index(Squishling) + 1)
+
+      INSTANCE_METHODS.filter_map do |name|
+        next if defined_in?(base, name)
+
+        owner = inherited.find { |mod| defined_in?(mod, name) }
+        "#{base}##{name} (from #{describe(owner)})" if owner
+      end
+    end
+
+    def defined_in?(mod, name)
+      mod.method_defined?(name, false) || mod.private_method_defined?(name, false)
+    end
+
+    def describe(owner)
+      owner.singleton_class? ? "#{owner.attached_object}'s class methods" : owner.to_s
+    end
+  end
+end

data/lib/squishling/configuration.rb

@@ -23,16 +23,27 @@ module Squishling
     # with_thinking; any other key (top_p, max_tokens, seed, ...) is passed to the provider as-is.
     attr_reader :default_params
 
+    # How every squishling class that doesn't declare its own harness uses its escalation (see Harness):
+    # :escalation (the default), :squishsum, :judged_squishsum, :ensemble, :judged_ensemble, or a Hash with
+    # type: and its options.
+    attr_reader :default_harness
+
     # Optional Logger for routing and escalation decisions.
     attr_accessor :logger
 
+    # Optional callable run after every LLM attempt with the raw output (see Squawk), e.g.
+    #   ->(output:, metadata:, error:) { Tracer.record(output, metadata, error) }
+    attr_reader :squawk
+
     def initialize
       @default_model = nil
       @default_escalation = nil
       @default_model_path = nil
       @default_provider = nil
       @default_params = {}
+      @default_harness = nil
       @logger = nil
+      @squawk = nil
     end
 
     def default_model=(model)
@@ -47,10 +58,18 @@ module Squishling
       @default_escalation = escalation
     end
 
+    def squawk=(hook)
+      @squawk = Squawk.validate(hook, "Squishling.configure")
+    end
+
     def default_params=(params)
       @default_params = Params.normalize(params, "default_params")
     end
 
+    def default_harness=(harness)
+      @default_harness = harness.nil? ? nil : Harness.normalize(harness, "default_harness")
+    end
+
     MAX_RETRIES_REMOVED = "max_retries was removed; use default_escalation (or a class/method escalation:) " \
                           "with attempts:, e.g. [{ model: \"claude-haiku-4-5\", attempts: 2 }]"
 

data/lib/squishling/definition.rb

@@ -9,42 +9,47 @@ module Squishling
 
     attr_reader :klass, :name, :call_context
 
-    def initialize(klass:, name:, instructions: nil, append_instructions: nil, output_schema: nil, model: nil,
-      provider: nil, params: nil, predicate: nil, fallback: nil, validator: nil, call_context: {})
+    def initialize(klass:, name:, purpose: nil, append_to_purpose: nil, output_schema: nil, model: nil,
+      provider: nil, params: nil, harness: nil, predicate: nil, fallback: nil, validator: nil, squawk: nil,
+      call_context: {})
       @klass = klass
       @name = name
-      @instructions = instructions
-      @append_instructions = append_instructions
+      @purpose = purpose
+      @append_to_purpose = append_to_purpose
       @output_schema = output_schema
       @model = model
       @provider = provider
       @params = params
+      @harness = harness
       @predicate = predicate
       @fallback = fallback
       @validator = validator
+      @squawk = squawk
       @call_context = call_context
     end
 
     # This definition with one call's overrides on top. The output schema, predicate, fallback, and validator
     # can't be overridden: the call must still return the method's result type.
-    def for_call(instructions: nil, append_instructions: nil, context: nil, model: nil, escalation: nil,
-      provider: nil, params: nil)
+    def for_call(purpose: nil, append_to_purpose: nil, context: nil, model: nil, escalation: nil,
+      provider: nil, params: nil, harness: nil)
       call_path = ModelPath.declare(model, escalation, "#{label} squish!")
       raise ConfigurationError, "#{label}: squish! provider: needs a model: or escalation:" if provider && !call_path
       unless context.nil? || (context.is_a?(Hash) && context.each_key.all?(NAME_KEY))
         raise ConfigurationError, "#{label}: squish! context: must be a Hash with String or Symbol keys"
       end
 
-      appended = Appendices.normalize(append_instructions, "#{label} squish!") unless append_instructions.nil?
+      appended = Appendices.normalize(append_to_purpose, "#{label} squish!") unless append_to_purpose.nil?
       call_params = params && Params.normalize(params, "#{label} squish! params")
+      call_harness = Harness.normalize(harness, "#{label} squish!") unless harness.nil?
       self.class.new(
         klass:, name:, output_schema: @output_schema, predicate: @predicate, fallback: @fallback,
-        validator: @validator,
-        instructions: instructions || @instructions,
-        append_instructions: [*@append_instructions, *appended],
+        validator: @validator, squawk: @squawk,
+        purpose: purpose || @purpose,
+        append_to_purpose: [*@append_to_purpose, *appended],
         model: call_path || @model, provider: call_path ? provider : @provider,
         # merge, not Params.resolve: a nil at the method level must still unset the class's key.
         params: call_params ? (@params || {}).merge(call_params) : @params,
+        harness: call_harness || @harness,
         call_context: @call_context.merge((context || {}).transform_keys(&:to_sym))
       )
     end
@@ -53,17 +58,17 @@ module Squishling
       "#{klass}##{name}"
     end
 
-    # The system prompt: the instructions, then each append_instructions section.
-    def instructions(receiver)
-      value = @instructions || klass.instructions
+    # The system prompt: the purpose, then each append_to_purpose section.
+    def purpose(receiver)
+      value = @purpose || klass.purpose
       value = receiver.instance_exec(&value) if value.is_a?(Proc)
       return value if value.nil? || value.empty?
 
-      [value, *Appendices.render(append_instructions, receiver, label)].join("\n\n")
+      [value, *Appendices.render(append_to_purpose, receiver, label)].join("\n\n")
     end
 
-    def append_instructions
-      Appendices.resolve(klass.squishling_append_instructions + (@append_instructions || []))
+    def append_to_purpose
+      Appendices.resolve(klass.squishling_append_to_purpose + (@append_to_purpose || []))
     end
 
     def schema
@@ -78,10 +83,15 @@ module Squishling
       config = Squishling.config
       entries, provider = [[@model, @provider], [klass.squishling_model_path, klass.squishling_provider],
                            [config.default_model_path, config.default_provider]].find(&:first)
-      entries ||= [{ model: nil, attempts: 1 }]
+      entries ||= [{ model: nil, attempts: 1, forward_rejected: true }]
       ModelPath.steps(entries, provider:, params:)
     end
 
+    # How the escalation is used (see Harness): the method's, the class's, the configured default, or :escalation.
+    def harness
+      @harness || klass.squishling_harness || Squishling.config.default_harness || Harness::DEFAULT
+    end
+
     # Generation params: config defaults, overridden key by key by the class, then by the method.
     def params
       Params.resolve(Squishling.config.default_params, klass.squishling_params, @params)
@@ -92,6 +102,12 @@ module Squishling
       @validator || klass.squishling_validator
     end
 
+    # The observability hook: the method's, else the class's, else the configured one. `false` at a level
+    # silences the levels above it.
+    def squawk
+      [@squawk, klass.squishling_squawk, Squishling.config.squawk].find { |hook| !hook.nil? } || nil
+    end
+
     def context_names
       klass.squishling_context_names
     end
@@ -115,18 +131,20 @@ module Squishling
       coerce(receiver.instance_exec(e, **inputs, &handler))
     end
 
-    # Deterministic return values: hashes are validated and turned into the typed result;
-    # anything else (including an already-built result) passes through.
+    # Deterministic and fallback return values: with an output_schema, every value is validated and
+    # typed like an LLM result. Without one, the value passes through untouched.
     def coerce(value)
-      value.is_a?(Hash) && schema ? build_result(value, squished: false) : value
+      schema ? build_result(value, squished: false) : value
     end
 
+    # A result of this schema's own class passes through; any other result is re-validated via to_h.
     def build_result(attrs, squished:)
       raise ConfigurationError, "#{label} has no output_schema" unless schema
-      return attrs if attrs.is_a?(Result::Instance)
+      return attrs if schema.result_class && attrs.is_a?(schema.result_class)
 
-      data = Schema.jsonify(attrs)
-      errors = schema.validate(data)
+      attrs = attrs.to_h if attrs.is_a?(Result::Instance)
+      data, errors = jsonify_return(attrs)
+      errors = schema.validate(data) if errors.empty?
       raise InvalidOutputError.new(errors:, raw: attrs, source: "Deterministic") if errors.any?
 
       schema.build(data, squished:)
@@ -162,6 +180,13 @@ module Squishling
 
     private
 
+    # Values JSON can't represent (NaN, Infinity, cycles) are invalid output, not a raw JSON error.
+    def jsonify_return(attrs)
+      [Schema.jsonify(attrs), []]
+    rescue JSON::GeneratorError, JSON::NestingError => e
+      [nil, [e.message]]
+    end
+
     # The implementation's parameters, beneath the prepended wrappers.
     def parameters
       Wrapper.implementation(klass.instance_method(name))&.parameters || []

data/lib/squishling/errors.rb

@@ -3,7 +3,7 @@
 module Squishling
   class Error < StandardError; end
 
-  # A programming or setup mistake (missing instructions/schema, non-strict schema, unknown model,
+  # A programming or setup mistake (missing purpose/schema, non-strict schema, unknown model,
   # missing API key). Never retried and never passed to squish_fallback.
   class ConfigurationError < Error; end
 
@@ -23,6 +23,27 @@ module Squishling
     end
   end
 
+  # A sampling harness's samples (squishsum or ensemble) were valid but didn't agree, and either no judge was declared
+  # (verdict nil) or the judge rejected both (verdict :neither, with its reason). candidates holds the two
+  # typed results, so a squish_fallback can still return one of them, and raw both as Hashes. models names the
+  # model behind each role (sample a, sample b, then the judge if one ran), not one entry per attempt; attempts
+  # is nil.
+  class DisagreementError < InvalidOutputError
+    attr_reader :candidates, :verdict, :reason
+
+    # detail: is text Squishling wrote itself (a judgment model's choice and probability) and is added to the
+    # message. A chat judge's reason is model-written and can quote the input, so it stays out of the message
+    # (and the logs); read it from #reason.
+    def initialize(candidates:, verdict: nil, reason: nil, detail: nil, models: nil)
+      @candidates = candidates
+      @verdict = verdict
+      @reason = reason
+      error = verdict ? "the judge rejected both samples" : "the two samples disagreed"
+      error += " (#{detail})" if detail
+      super(errors: [error], raw: candidates.map(&:to_h), models:)
+    end
+  end
+
   # The LLM call itself failed (rate limit, server error, timeout, connection) after RubyLLM's own
   # HTTP retries. The original exception is available as #cause.
   class LLMError < Error; end

data/lib/squishling/harness.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Squishling
+  # How a squished call uses its escalation. Declared as a type, or a Hash with the type and its options:
+  #   harness: :squishsum
+  #   harness: { type: :judged_squishsum, judge: "claude-opus-5-5", compare: ->(a, b, **) { a.team == b.team } }
+  # :escalation (the default) tries each attempt in order until an output passes. :squishsum asks the first
+  # escalation step twice, concurrently, and accepts the output only when both samples agree. :ensemble asks
+  # the first and second escalation steps once each instead (a cross-model check). :judged_squishsum and
+  # :judged_ensemble hand disagreeing samples to a judge that picks one or rejects both.
+  class Harness
+    TYPES = %i[escalation squishsum judged_squishsum ensemble judged_ensemble].freeze
+    ENSEMBLE_TYPES = %i[ensemble judged_ensemble].freeze
+    JUDGED_TYPES = %i[judged_squishsum judged_ensemble].freeze
+    KEYS = %i[type judge judge_instructions compare].freeze
+
+    # A judge is one step: a model name or a Hash with the escalation step keys (except order:), plus
+    # type: (:chat, the default, or :judgment for a System One decision model through RubyLLM.judge) and,
+    # for :judgment, min_confidence: (the probability the chosen candidate needs).
+    JUDGE_TYPES = %i[chat judgment].freeze
+    JUDGE_KEYS = %i[type min_confidence].freeze
+    # Request keys RubyLLM's judgment protocols own (model and input are already reserved params).
+    JUDGMENT_RESERVED_PARAMS = %i[state questions].freeze
+    DEFAULT_MIN_CONFIDENCE = 0.8
+
+    DEFAULT_JUDGE_INSTRUCTIONS = <<~TEXT.strip
+      You are an impartial judge. Two independent attempts at the same operation returned different outputs,
+      candidate "a" and candidate "b". Both already match the required output format, so judge only their
+      content. You are given the operation's purpose and its input. Decide which candidate correctly and
+      faithfully carries out the purpose for this input. If both do (for example, they differ only in
+      wording), choose either one, preferring "a". Choose "neither" only when both are wrong or you can't tell
+      whether either is correct. Never combine them or invent a third answer.
+    TEXT
+
+    attr_reader :type, :judge, :judge_instructions, :compare
+
+    class << self
+      def normalize(value, label)
+        case value
+        when Symbol, String then new(type: type_for(value, label))
+        when Hash then from_hash(value, label)
+        else
+          raise ConfigurationError, "#{label}: harness must be one of #{TYPES.join(', ')} or a Hash with type:, " \
+                                    "got #{value.inspect}"
+        end
+      end
+
+      private
+
+      def from_hash(hash, label)
+        hash = hash.transform_keys(&:to_sym)
+        unknown = hash.keys - KEYS
+        raise ConfigurationError, "#{label}: unknown harness option(s) #{unknown.join(', ')}" if unknown.any?
+        raise ConfigurationError, "#{label}: a harness Hash needs type:" unless hash.key?(:type)
+
+        type = type_for(hash[:type], label)
+        check_options!(type, hash, label)
+        new(type:, judge: hash[:judge].nil? ? nil : normalize_judge(hash[:judge], label),
+          judge_instructions: hash[:judge_instructions], compare: hash[:compare])
+      end
+
+      def type_for(value, label)
+        type = value.to_s.to_sym if value.is_a?(Symbol) || value.is_a?(String)
+        return type if TYPES.include?(type)
+
+        raise ConfigurationError, "#{label}: unknown harness #{value.inspect} (use #{TYPES.join(', ')})"
+      end
+
+      def check_options!(type, hash, label)
+        judge_options = %i[judge judge_instructions].select { |key| hash.key?(key) }
+        if judge_options.any? && !JUDGED_TYPES.include?(type)
+          options = judge_options.map { |key| "#{key}:" }.join(", ")
+          raise ConfigurationError,
+            "#{label}: #{options} can only be used with the #{JUDGED_TYPES.join(' and ')} harnesses"
+        end
+        if hash.key?(:compare) && type == :escalation
+          raise ConfigurationError, "#{label}: compare: only applies to the sampling harnesses (squishsum and ensemble)"
+        end
+        unless hash[:compare].nil? || hash[:compare].is_a?(Proc)
+          raise ConfigurationError, "#{label}: compare: must be a Proc, got #{hash[:compare].class}"
+        end
+
+        instructions = hash[:judge_instructions]
+        return if instructions.nil? || instructions.is_a?(Proc)
+        return if instructions.is_a?(String) && !instructions.strip.empty?
+
+        raise ConfigurationError, "#{label}: judge_instructions: must be a non-blank String or a Proc"
+      end
+
+      # The judge as a normalized escalation step (see ModelPath), plus its type and min_confidence.
+      def normalize_judge(judge, label)
+        judge_label = "#{label} judge"
+        return ModelPath.normalize_step(judge, judge_label).merge(type: :chat) unless judge.is_a?(Hash)
+
+        judge = judge.transform_keys(&:to_sym)
+        raise ConfigurationError, "#{judge_label}: a judge is one step, so it takes no order:" if judge.key?(:order)
+
+        type = judge.fetch(:type, :chat)
+        type = type.to_sym if type.is_a?(String)
+        unless JUDGE_TYPES.include?(type)
+          raise ConfigurationError,
+            "#{judge_label}: type: must be one of #{JUDGE_TYPES.join(', ')}, got #{type.inspect}"
+        end
+
+        if type == :chat && judge.key?(:min_confidence)
+          raise ConfigurationError, "#{judge_label}: min_confidence: only applies to type: :judgment judges"
+        end
+
+        step = ModelPath.normalize_step(judge.except(*JUDGE_KEYS), judge_label).merge(type:)
+        return step unless type == :judgment
+
+        reserved = (step[:params] || {}).keys & JUDGMENT_RESERVED_PARAMS
+        if reserved.any?
+          raise ConfigurationError, "#{judge_label}: #{reserved.join(', ')} can't be set through params " \
+                                    "(controlled by Squishling/RubyLLM)"
+        end
+
+        step.merge(min_confidence: min_confidence(judge, judge_label))
+      end
+
+      def min_confidence(judge, label)
+        value = judge.fetch(:min_confidence, DEFAULT_MIN_CONFIDENCE)
+        return value.to_f if value.is_a?(Numeric) && value.between?(0, 1)
+
+        raise ConfigurationError, "#{label}: min_confidence: must be a number from 0 to 1, got #{value.inspect}"
+      end
+    end
+
+    def initialize(type:, judge: nil, judge_instructions: nil, compare: nil)
+      @type = type
+      @judge = judge
+      @judge_instructions = judge_instructions
+      @compare = compare
+      freeze
+    end
+
+    DEFAULT = new(type: :escalation)
+
+    # Whether the call asks two samples (squishsum and ensemble harnesses) rather than walking the escalation.
+    def squishsum?
+      type != :escalation
+    end
+
+    # Whether the two samples come from the first two escalation steps instead of both from the first.
+    def ensemble?
+      ENSEMBLE_TYPES.include?(type)
+    end
+
+    def judged?
+      JUDGED_TYPES.include?(type)
+    end
+  end
+end