squishling 0.2.0 → 0.4.0

data/lib/squishling/definition.rb

@@ -7,45 +7,52 @@ module Squishling
     # Matches the keys a squish! context: Hash may use.
     NAME_KEY = ->(key) { key.is_a?(String) || key.is_a?(Symbol) }
 
-    attr_reader :klass, :name, :call_context
+    attr_reader :klass, :name, :call_context, :handed_off
 
-    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: {}, handed_off: false)
       @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
+      @handed_off = handed_off
     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,
-        call_context: @call_context.merge((context || {}).transform_keys(&:to_sym))
+        harness: call_harness || @harness,
+        call_context: @call_context.merge((context || {}).transform_keys(&:to_sym)),
+        handed_off: true # only squish! builds a definition this way; it is not part of a declared one
       )
     end
 
@@ -53,17 +60,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
@@ -73,13 +80,20 @@ module Squishling
 
     # One ModelPath::Step per attempt, from the first level (method, class, or config) that declares a model
     # or escalation, or a single attempt on RubyLLM's default model. A provider travels with the model declared
-    # at the same level, so a per-method Anthropic model never inherits a class-level OpenAI provider.
+    # at the same level, so a per-method Anthropic model never inherits a class-level OpenAI provider. Models
+    # tied on priority are rotated by this method's call count (see Rotation).
     def escalation_path
       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 }]
-      ModelPath.steps(entries, provider:, params:)
+      entries ||= [{ model: nil, attempts: 1, forward_rejected: true }]
+      turn = ModelPath.rotating?(entries) ? Rotation.advance(klass, name) : 0
+      ModelPath.steps(entries, provider:, params:, turn:)
+    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.
@@ -92,6 +106,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 +135,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 +184,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 harness's samples (the squishsum harnesses', or a custom one's) 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 typed results, so a squish_fallback can still return one of them, and raw all of them 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/base.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Squishling
+  class Harness
+    # The base of every harness: the built-ins, and your own. Subclass it, declare the options it takes, define
+    # call, and register it (Squishling.register_harness):
+    #
+    #   class Tiebreaker < Squishling::Harness::Base
+    #     option :tiebreaker, :step, required: true
+    #
+    #     def call(run, tiebreaker:)
+    #       first, second = run.samples(run.stages.first(2))
+    #       run.agree?(first, second) ? first : run.escalate(tiebreaker)
+    #     end
+    #   end
+    #   Squishling.register_harness(:tiebreaker, Tiebreaker)
+    #
+    # call gets a Run (the primitives that ask for samples, escalate, and judge) and the validated options as
+    # keywords, and returns the accepted typed result, or raises Squishling::InvalidOutputError (a
+    # DisagreementError when samples disagreed) or Squishling::LLMError, which squish_fallback handles.
+    class Base
+      Option = Data.define(:name, :type, :required)
+
+      # The kinds of parameter that can receive the run, call's first argument.
+      RUN_PARAMETERS = %i[req opt rest].freeze
+      KEYWORD_PARAMETERS = %i[key keyreq].freeze
+      REQUIRED_PARAMETERS = %i[req keyreq].freeze
+
+      class << self
+        # Declares an option: its name, one of OptionTypes::TYPES (or a callable that normalizes the value, see
+        # OptionTypes), and whether it must be given. A harness is declared with { type: :name, option_name: value },
+        # and the options are checked up front.
+        def option(name, type, required: false)
+          unless OptionTypes.type?(type)
+            raise ConfigurationError, "option #{name.inspect}: type must be one of #{OptionTypes::TYPES.join(', ')} " \
+                                      "or a callable taking (value, label, name), got #{type.inspect}"
+          end
+
+          raise ConfigurationError, "declare options on a subclass of Harness::Base, not on Base" if equal?(Base)
+          if name.to_sym == :type
+            raise ConfigurationError, "option :type is taken: it names the harness in a harness Hash"
+          end
+
+          own_options[name.to_sym] = Option.new(name: name.to_sym, type:, required: required ? true : false)
+        end
+
+        # The declared options by name, including those of the superclass.
+        def options
+          inherited = equal?(Base) ? {} : superclass.options
+          inherited.merge(own_options)
+        end
+
+        # The options as given in a harness Hash (without type:): checked and normalized, or ConfigurationError.
+        # An option given as nil counts as not given.
+        def normalize_options(given, label)
+          given = given.transform_keys(&:to_sym)
+          unknown = given.keys - options.keys
+          raise ConfigurationError, "#{label}: unknown harness option(s) #{unknown.join(', ')}" if unknown.any?
+
+          given = given.compact
+
+          missing = options.values.select { |option| option.required && !given.key?(option.name) }
+          if missing.any?
+            raise ConfigurationError, "#{label}: harness option(s) #{missing.map(&:name).join(', ')} required"
+          end
+
+          normalized = given.to_h do |name, value|
+            [name, OptionTypes.check(options.fetch(name).type, value, label, name)]
+          end
+          validate_options!(normalized, label)
+          normalized.freeze
+        end
+
+        # Override to check options against each other; raise ConfigurationError (with the label) to reject.
+        def validate_options!(_options, _label); end
+
+        # Rejects a class that can't run as the harness registered under name: not a Base subclass, no call,
+        # or a call that doesn't take the run and each declared option.
+        def check_registrable!(klass, name)
+          unless klass.is_a?(Class) && klass <= Base && klass != Base
+            raise ConfigurationError, "harness #{name.inspect} must be a subclass of Squishling::Harness::Base, " \
+                                      "got #{klass.inspect}"
+          end
+          if klass.instance_method(:call).owner == Base
+            raise ConfigurationError, "harness #{name.inspect} must define call(run, **options)"
+          end
+          unless klass.public_method_defined?(:call)
+            raise ConfigurationError, "harness #{name.inspect}: call must be public"
+          end
+
+          check_signature!(klass, name)
+        end
+
+        private
+
+        def own_options
+          @own_options ||= {}
+        end
+
+        def check_signature!(klass, name)
+          parameters = klass.instance_method(:call).parameters
+          unless RUN_PARAMETERS.include?(parameters.first&.first)
+            raise ConfigurationError, "harness #{name.inspect}: call must take the run as its first argument"
+          end
+          if parameters.count { |type, _| type == :req } > 1
+            raise ConfigurationError, "harness #{name.inspect}: call takes the run, then options as keywords only"
+          end
+          if klass.instance_method(:initialize).parameters.any? { |type, _| REQUIRED_PARAMETERS.include?(type) }
+            raise ConfigurationError, "harness #{name.inspect}: a harness is created without arguments, " \
+                                      "so initialize can't require any"
+          end
+
+          accepted = parameters.filter_map { |type, key| key if KEYWORD_PARAMETERS.include?(type) }
+          required = parameters.filter_map { |type, key| key if type == :keyreq }
+          # A ** takes every declared option, but not an option's absence.
+          missing = parameters.any? { |type, _| type == :keyrest } ? [] : klass.options.keys - accepted
+          undeclared = required - klass.options.keys
+          # An option that may be left out can't be a required keyword.
+          optional = required & klass.options.values.reject(&:required).map(&:name)
+          return if missing.empty? && undeclared.empty? && optional.empty?
+
+          problems = [("doesn't take #{missing.join(', ')}" if missing.any?),
+                      ("requires undeclared #{undeclared.join(', ')}" if undeclared.any?),
+                      ("requires optional #{optional.join(', ')} (give it a default)" if optional.any?)].compact
+          raise ConfigurationError, "harness #{name.inspect}: call #{problems.join(' and ')} " \
+                                    "(declare each option with option, and take it as a keyword)"
+        end
+      end
+
+      # The harness itself; subclasses define it.
+      def call(_run, **)
+        raise ConfigurationError, "#{self.class} must define call(run, **options)"
+      end
+    end
+  end
+end

data/lib/squishling/harness/escalation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Squishling
+  class Harness
+    # The default: each attempt of the escalation, in order, until an output passes the schema and squish_validate.
+    class Escalation < Base
+      def self.normalize_options(given, label)
+        if given.transform_keys(&:to_sym).key?(:compare)
+          raise ConfigurationError, "#{label}: compare: only applies to the squishsum harnesses"
+        end
+
+        super
+      end
+
+      def call(run)
+        run.escalate
+      end
+    end
+
+    Registry.register_built_in(:escalation, Escalation)
+  end
+end

data/lib/squishling/harness/judged_squishsum.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Squishling
+  class Harness
+    # Like Squishling::Harness::Squishsum, but samples that disagree go to a judge, which picks one or rejects both.
+    # A judge is one step: a model name or a Hash with the escalation step keys (except priority:), 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).
+    class JudgedSquishsum < Base
+      # Request keys RubyLLM's judgment protocols own (model and input are already reserved params).
+      JUDGMENT_RESERVED_PARAMS = %i[state questions].freeze
+      private_constant :JUDGMENT_RESERVED_PARAMS
+
+      class << self
+        # A judge as a normalized escalation step (see ModelPath), plus its type and min_confidence. label is the
+        # declaration site and name the option it came from. Internal.
+        def normalize_judge(judge, label, name = :judge)
+          judge_label = "#{label} #{name}"
+          return ModelPath.normalize_step(judge, judge_label).merge(type: :chat) unless judge.is_a?(Hash)
+
+          judge = judge.transform_keys(&:to_sym)
+          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::STEP_KEYS), judge_label).merge(type:)
+          ModelPath.single_step!(step, "#{judge_label}: a judge is one step, so it")
+          return step unless type == :judgment
+
+          Params.reject_reserved!(step[:params] || {}, JUDGMENT_RESERVED_PARAMS, judge_label)
+
+          step.merge(min_confidence: min_confidence(judge, judge_label))
+        end
+
+        # The judge's prompt: a non-blank String, or a Proc evaluated against the instance. Internal.
+        def normalize_instructions(value, label, name = :judge_instructions)
+          return value if value.is_a?(Proc)
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+
+          raise ConfigurationError, "#{label}: #{name}: must be a non-blank String or a Proc"
+        end
+
+        private
+
+        def min_confidence(judge, label)
+          value = judge.fetch(:min_confidence, Judge::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
+
+      option :compare, :proc
+      option :judge, ->(value, label, name) { normalize_judge(value, label, name) }
+      option :judge_instructions, ->(value, label, name) { normalize_instructions(value, label, name) }
+
+      def call(run, compare: nil, judge: nil, judge_instructions: nil)
+        stage = run.stages.first
+        # The judge is resolved before any sample is requested, so a missing one fails before costing anything.
+        judge = run.judge(judge:, instructions: judge_instructions)
+        first, second = run.samples([stage, stage])
+        return first if run.agree?(first, second, compare)
+
+        run.log("samples disagreed, asking the judge (#{judge.step.display_name})")
+        verdict = judge.verdict(first, second)
+        return { a: first, b: second }.fetch(verdict.choice) unless verdict.choice == :neither
+
+        models = [stage.first.model] * 2
+        raise DisagreementError.new(candidates: [first, second], verdict: :neither, reason: verdict.reason,
+          detail: verdict.detail, models: models + [judge.step.model])
+      end
+    end
+
+    Registry.register_built_in(:judged_squishsum, JudgedSquishsum)
+  end
+end

data/lib/squishling/harness/option_types.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Squishling
+  class Harness
+    # The types a harness option can declare (see Base.option). Each checks a given value and returns it
+    # normalized, or raises ConfigurationError, so a bad option fails before any request is made.
+    #   :step         a model name or a step Hash (model:, provider:, params:, attempts:, forward_rejected:)
+    #   :proc, :string, :symbol, :integer, :boolean
+    # A harness with a shape of its own declares the type as a callable instead, which gets the value, the
+    # declaration site, and the option's name, and returns the normalized value (or raises ConfigurationError).
+    module OptionTypes
+      TYPES = %i[step proc string symbol integer boolean].freeze
+
+      module_function
+
+      # Whether type is one a harness can declare: a built-in one above, or a callable that takes the value, the
+      # label, and the name.
+      def type?(type)
+        TYPES.include?(type) || (type.respond_to?(:call) && takes_three?(type))
+      end
+
+      # Whether the callable can be called with three positional arguments. One without a parameter list
+      # (an object with its own call) is trusted.
+      def takes_three?(callable)
+        return true if callable.is_a?(Proc) && !callable.lambda? # a proc drops the arguments it doesn't name
+
+        method = callable.is_a?(Proc) || callable.is_a?(Method) ? callable : callable.method(:call)
+        parameters = method.parameters.map(&:first)
+        return false if parameters.include?(:keyreq)
+        return true if parameters.include?(:rest)
+
+        3.between?(parameters.count(:req), parameters.count(:req) + parameters.count(:opt))
+      end
+
+      # The value as the type's normalized form. label is the declaration site, name the option.
+      def check(type, value, label, name)
+        return deep_freeze(type.call(value, label, name)) if type.respond_to?(:call)
+
+        send(:"check_#{type}", value, "#{label} #{name}", "#{label}: #{name}:")
+      end
+
+      def check_step(value, label, _where)
+        step = ModelPath.normalize_step(value, label)
+        ModelPath.single_step!(step, "#{label}: a harness step")
+        deep_freeze(step)
+      end
+
+      def check_proc(value, _label, where)
+        check_kind(value, Proc, "a Proc", where)
+      end
+
+      def check_string(value, _label, where)
+        return value.dup.freeze if value.is_a?(String)
+
+        raise ConfigurationError, "#{where} must be a String, got #{value.class}"
+      end
+
+      def check_symbol(value, _label, where)
+        return value.to_sym if value.is_a?(Symbol) || value.is_a?(String)
+
+        raise ConfigurationError, "#{where} must be a Symbol, got #{value.class}"
+      end
+
+      def check_integer(value, _label, where)
+        check_kind(value, Integer, "an Integer", where)
+      end
+
+      def check_boolean(value, _label, where)
+        return value if [true, false].include?(value)
+
+        raise ConfigurationError, "#{where} must be true or false, got #{value.inspect}"
+      end
+
+      # The value itself when it is a kind, else a ConfigurationError saying what was expected.
+      def check_kind(value, kind, description, where)
+        return value if value.is_a?(kind)
+
+        raise ConfigurationError, "#{where} must be #{description}, got #{value.class}"
+      end
+
+      # A frozen copy: normalized steps are shared by every call that uses the declaration, so none can change
+      # one, and the caller's own objects stay as they were.
+      def deep_freeze(value)
+        case value
+        when Hash then value.to_h { |key, item| [key, deep_freeze(item)] }.freeze
+        when Array then value.map { |item| deep_freeze(item) }.freeze
+        when String then value.dup.freeze
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/squishling/harness/registry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Squishling
+  class Harness
+    # The harness types by name: the built-ins, registered as they load, and your own (Squishling.register_harness).
+    # Shared across threads, so every read and write is under the lock.
+    module Registry
+      NAME = /\A[a-z][a-z0-9_]*\z/
+
+      LOCK = Mutex.new
+      private_constant :LOCK
+      @built_in = {}
+      @custom = {}
+
+      class << self
+        def register_built_in(name, klass)
+          LOCK.synchronize { @built_in[name] = klass }
+        end
+
+        # Registers a harness class (or a block, which becomes the body of a Base subclass) under a name.
+        def register(name, klass = nil, &block)
+          raise ConfigurationError, "register_harness takes a class or a block, not both" if klass && block
+          raise ConfigurationError, "register_harness needs a Harness::Base subclass or a block" unless klass || block
+
+          name = checked_name(name)
+          klass = Class.new(Base, &block) if block
+          Base.check_registrable!(klass, name)
+          LOCK.synchronize do
+            raise ConfigurationError, "harness #{name.inspect} is already registered" if taken?(name)
+
+            @custom[name] = klass
+          end
+          klass
+        end
+
+        def fetch(name)
+          LOCK.synchronize { @built_in[name] || @custom[name] }
+        end
+
+        def names
+          LOCK.synchronize { @built_in.keys + @custom.keys }
+        end
+
+        # Forgets the registered harnesses; the built-ins stay.
+        def reset!
+          LOCK.synchronize { @custom.clear }
+        end
+
+        private
+
+        def checked_name(name)
+          unless name.is_a?(Symbol) || name.is_a?(String)
+            raise ConfigurationError, "a harness name must be a Symbol or String, got #{name.inspect}"
+          end
+
+          name = name.to_sym
+          return name if NAME.match?(name)
+
+          raise ConfigurationError,
+            "harness name #{name.inspect} must be lowercase letters, digits, and underscores, starting with a letter"
+        end
+
+        def taken?(name)
+          @built_in.key?(name) || @custom.key?(name)
+        end
+      end
+    end
+  end
+end

data/lib/squishling/harness/squishsum.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Squishling
+  class Harness
+    # Two samples on the escalation's first step, asked concurrently. Identical outputs (or ones compare: calls
+    # equal) are accepted; different ones raise DisagreementError.
+    class Squishsum < Base
+      option :compare, :proc
+
+      def call(run, compare: nil)
+        stage = run.stages.first
+        first, second = run.samples([stage, stage])
+        return first if run.agree?(first, second, compare)
+
+        run.log("samples disagreed")
+        raise DisagreementError.new(candidates: [first, second], models: [stage.first.model] * 2)
+      end
+    end
+
+    Registry.register_built_in(:squishsum, Squishsum)
+  end
+end