squishling 0.3.0 → 0.5.0

data/lib/squishling/class_methods.rb

@@ -9,7 +9,7 @@ module Squishling
     #   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.
+    # Pass provider: alongside model: for models missing from RubyLLM's registry (the RubyLLM adapter), e.g.
     #   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.
@@ -19,11 +19,19 @@ module Squishling
     #   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
+    # max_total_output_tokens:/max_total_input_tokens: cap the tokens one call may use across all its requests
+    # (see Budget); false lifts a cap inherited from the parent class or the configuration:
+    #   squishling max_total_output_tokens: 25_000
+    # squawk: is called after each LLM attempt (narrowed by squawk_on:) with the raw output (see
+    # Configuration#squawk); false silences
     # an inherited one:
     #   squishling squawk: ->(output:, metadata:, error:) { Tracer.record(output, metadata, error) }
+    # squawk_on: limits which attempts reach the hook: :all (the default), :rejections, :retries, :final, or a
+    # list of them (any one holding runs the hook):
+    #   squishling squawk: hook, squawk_on: %i[rejections final]
     def squishling(model: nil, escalation: nil, provider: nil, params: nil, harness: nil, purpose: nil,
-      append_to_purpose: nil, output_schema: nil, squawk: nil)
+      append_to_purpose: nil, output_schema: nil, squawk: nil, squawk_on: nil, max_total_output_tokens: nil,
+      max_total_input_tokens: 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
@@ -41,14 +49,24 @@ module Squishling
       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?
+      declare_squawk(squawk, squawk_on)
+      declare_budget(max_total_output_tokens, max_total_input_tokens)
       self
     end
 
+    # The token limits declared on this class and its ancestors, limit by limit (see Budget).
+    def squishling_budget
+      squishling_inherited(:squishling_budget, {}).merge(@squishling_budget || {})
+    end
+
     def squishling_squawk
       squishling_lookup(:@squishling_squawk)
     end
 
+    def squishling_squawk_on
+      squishling_lookup(:@squishling_squawk_on)
+    end
+
     # The class's (or nearest ancestor's) model or escalation, as normalized steps.
     def squishling_model_path
       squishling_lookup(:@squishling_model_path)
@@ -147,11 +165,14 @@ module Squishling
     #   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
+    #                   harness: :squishsum, max_total_output_tokens: 25_000,
+    #                   squawk: ->(output:, error:, **) { Tracer.record(output, error) },
+    #                   squawk_on: :retries do
     #     string :priority
     #   end
     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)
+      provider: nil, params: nil, harness: nil, when: nil, fallback: nil, validate: nil, squawk: nil,
+      squawk_on: nil, max_total_output_tokens: nil, max_total_input_tokens: 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
@@ -162,8 +183,11 @@ module Squishling
         append_to_purpose = Appendices.normalize(append_to_purpose, "#{self} squish append_to_purpose")
       end
       squawk = Squawk.validate(squawk, "#{self} squish")
+      squawk_on = Squawk.validate_on(squawk_on, "#{self} squish")
+      budget = Budget.build("#{self} squish", output: max_total_output_tokens, input: max_total_input_tokens)
       options = { purpose:, append_to_purpose:, output_schema: schema, model:, provider:, params:, harness:,
-                  predicate: binding.local_variable_get(:when), fallback:, validator: validate, squawk: }.compact
+                  predicate: binding.local_variable_get(:when), fallback:, validator: validate, squawk:,
+                  squawk_on:, budget: }.compact
 
       names.map(&:to_sym).each do |name|
         (@squishling_methods ||= {})[name] = options
@@ -192,8 +216,20 @@ module Squishling
 
     private
 
+    # nil leaves a level unset (so the parent's applies); false for squawk: is stored, to silence it.
+    def declare_squawk(squawk, squawk_on)
+      @squishling_squawk = Squawk.validate(squawk, to_s) unless squawk.nil?
+      @squishling_squawk_on = Squawk.validate_on(squawk_on, "#{self} squishling") unless squawk_on.nil?
+    end
+
+    # Adds the class's own token limits to those it declared before.
+    def declare_budget(output, input)
+      @squishling_budget = (@squishling_budget || {}).merge(Budget.build(to_s, output:, input:)).freeze
+    end
+
     # Each class gets its own prepended wrapper so overrides in subclasses are routed too.
     def squishling_install_wrapper
+      ClassRegistry.register(self)
       @squishling_wrapper = Wrapper.new
       prepend(@squishling_wrapper)
 

data/lib/squishling/class_registry.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Every class that includes Squishling (and each subclass of one), so they can be verified ahead of runtime.
+  # Held weakly, so classes replaced by code reloading (e.g. Rails in development) can be collected; a class that is
+  # replaced but not yet collected is left out of the list. Shared across threads, so every access is under the lock.
+  module ClassRegistry
+    LOCK = Mutex.new
+    GONE = Object.new.freeze
+    UNKNOWN = Object.new.freeze
+    private_constant :LOCK, :GONE, :UNKNOWN
+
+    @classes = ObjectSpace::WeakMap.new
+
+    class << self
+      def register(klass)
+        LOCK.synchronize { @classes[klass] = true }
+        klass
+      end
+
+      # The live classes, in no particular order, as a snapshot.
+      def classes
+        LOCK.synchronize { @classes.keys }.reject { |klass| replaced?(klass) }
+      end
+
+      # Forgets every class, e.g. between specs.
+      def reset!
+        LOCK.synchronize { @classes = ObjectSpace::WeakMap.new }
+      end
+
+      private
+
+      # A named class whose constant is gone or now holds another object (a reload has replaced it). Anonymous
+      # classes have no constant to go stale, and a name that can't be walked (under an anonymous module, a temporary
+      # name) is taken as live.
+      def replaced?(klass)
+        name = Module.instance_method(:name).bind_call(klass) # the class may define its own .name
+        return false unless name
+
+        found = lookup(name)
+        !found.equal?(UNKNOWN) && !found.equal?(klass)
+      end
+
+      def lookup(name)
+        name.split("::").reduce(Object) do |scope, constant|
+          found = child(scope, constant)
+          return found if found.equal?(GONE) || found.equal?(UNKNOWN)
+
+          found
+        end
+      end
+
+      # The constant in scope, without autoloading it: GONE when it is missing or a pending autoload (Zeitwerk resets
+      # a reloaded constant to one, and loading it would run app code), UNKNOWN when the name can't be walked.
+      def child(scope, constant)
+        return UNKNOWN unless scope.is_a?(Module) && constant.match?(/\A[A-Z]\w*\z/)
+        return GONE if scope.autoload?(constant, false) || !scope.const_defined?(constant, false)
+
+        scope.const_get(constant, false)
+      end
+    end
+  end
+end

data/lib/squishling/configuration.rb

@@ -3,7 +3,7 @@
 module Squishling
   class Configuration
     # Model used by every squishling class that doesn't declare its own (a single attempt).
-    # When neither this nor default_escalation is set, RubyLLM's own default model is used.
+    # When neither this nor default_escalation is set, the adapter's own default model is used.
     attr_reader :default_model
 
     # Models tried in order by every squishling class that doesn't declare its own, e.g.
@@ -14,28 +14,53 @@ module Squishling
     # The validated default_model or default_escalation steps (nil when neither is set).
     attr_reader :default_model_path
 
-    # Provider for default_model/default_escalation steps that don't name their own (e.g. :openai). Only
-    # needed for models missing from RubyLLM's registry.
+    # Provider for default_model/default_escalation steps that don't name their own (e.g. :openai). What it means is
+    # up to the adapter: the RubyLLM adapter needs it only for models missing from RubyLLM's registry, and the
+    # OpenAI-compatible adapter ignores it.
     attr_accessor :default_provider
 
     # Generation params applied to every call, overridable per class and per method.
-    # :temperature and :thinking ({ effort:, budget: }) map to RubyLLM's with_temperature and
-    # with_thinking; any other key (top_p, max_tokens, seed, ...) is passed to the provider as-is.
+    # :temperature, :max_output_tokens and :thinking ({ effort:, budget: }) are portable and translated by the
+    # adapter for its provider; any other key (top_p, 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.
+    # :escalation (the default), :squishsum, :judged_squishsum, a harness you registered, or a Hash with type: and
+    # its options.
     attr_reader :default_harness
 
+    # Most output tokens, and most input tokens, one squished call may use across all its requests (nil, the default,
+    # sets no limit). A call that has used this many stops with a BudgetExhaustedError instead of making another
+    # attempt; overridable per class, method and squish! call (see Budget).
+    attr_reader :default_max_total_output_tokens, :default_max_total_input_tokens
+
     # 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.
+    # Optional callable run after each LLM attempt (narrowed by squawk_on) with the raw output (see Squawk), e.g.
     #   ->(output:, metadata:, error:) { Tracer.record(output, metadata, error) }
     attr_reader :squawk
 
+    # Which attempts reach the squawk hook: :all (the default), :rejections (attempts that errored), :retries (those
+    # plus any accepted attempt after the first), :final (the last attempt the escalation allows), or a list of
+    # them. Also settable per class and per method.
+    attr_reader :squawk_on
+
+    # Optional around-style hook wrapped around every provider request (see Observer): an object responding to
+    # around(call) { ... }, or :coolhand. nil (the default) uses the Coolhand observer when the coolhand gem is
+    # loaded and configured, and nothing otherwise; false never wraps.
+    attr_reader :observer
+
+    # How Squishling reaches a model (see Adapter): :ruby_llm, :openai_compatible, an adapter you registered, a Hash
+    # with type: and that adapter's options, or an adapter instance. nil (the default) uses RubyLLM when the ruby_llm
+    # gem is available. Built when assigned, so a mistake fails at setup rather than on the first request.
+    attr_reader :adapter
+
     def initialize
+      @adapter = nil
+      @detected_adapter = nil
+      @adapter_lock = Mutex.new
+      @observer = nil
       @default_model = nil
       @default_escalation = nil
       @default_model_path = nil
@@ -44,6 +69,7 @@ module Squishling
       @default_harness = nil
       @logger = nil
       @squawk = nil
+      @squawk_on = :all
     end
 
     def default_model=(model)
@@ -58,10 +84,48 @@ module Squishling
       @default_escalation = escalation
     end
 
+    def adapter=(adapter)
+      built = adapter.nil? ? nil : Adapter.build(adapter, "Squishling.configure")
+      @adapter_lock.synchronize do
+        @adapter = built
+        @detected_adapter = nil
+      end
+    end
+
+    # The adapter requests go through: the configured one, else RubyLLM's (when its gem is available) built on first
+    # use. Raises ConfigurationError when there is neither.
+    def resolved_adapter
+      @adapter_lock.synchronize { @adapter || (@detected_adapter ||= Adapter.detect) }
+    end
+
+    def default_max_total_output_tokens=(tokens)
+      @default_max_total_output_tokens = Budget.build("default_max_total_output_tokens", output: tokens)[:output]
+    end
+
+    def default_max_total_input_tokens=(tokens)
+      @default_max_total_input_tokens = Budget.build("default_max_total_input_tokens", input: tokens)[:input]
+    end
+
+    # The configured limits as a Budget level.
+    def default_budget
+      { output: default_max_total_output_tokens, input: default_max_total_input_tokens }.compact
+    end
+
     def squawk=(hook)
       @squawk = Squawk.validate(hook, "Squishling.configure")
     end
 
+    def squawk_on=(on)
+      @squawk_on = Squawk.validate_on(on, "Squishling.configure") || :all
+    end
+
+    def observer=(observer)
+      Observer.validate(observer, "Squishling.configure")
+      # A named observer is built now, so a missing gem fails at setup rather than on the first request.
+      Observer.resolve(observer) if observer.is_a?(Symbol)
+      @observer = observer
+    end
+
     def default_params=(params)
       @default_params = Params.normalize(params, "default_params")
     end

data/lib/squishling/definition.rb

@@ -7,11 +7,14 @@ 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
+    # One attempt on RubyLLM's default model, when no level declares a model.
+    DEFAULT_STEP = { model: nil, attempts: 1, forward_rejected: true }.freeze
+
+    attr_reader :klass, :name, :call_context, :handed_off
 
     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: {})
+      squawk_on: nil, budget: nil, call_context: {}, handed_off: false)
       @klass = klass
       @name = name
       @purpose = purpose
@@ -25,13 +28,16 @@ module Squishling
       @fallback = fallback
       @validator = validator
       @squawk = squawk
+      @squawk_on = squawk_on
+      @budget = budget || {}
       @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(purpose: nil, append_to_purpose: nil, context: nil, model: nil, escalation: nil,
-      provider: nil, params: nil, harness: nil)
+      provider: nil, params: nil, harness: nil, max_total_output_tokens: nil, max_total_input_tokens: 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))
@@ -41,16 +47,18 @@ module Squishling
       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?
+      call_budget = Budget.build("#{label} squish!", output: max_total_output_tokens, input: max_total_input_tokens)
       self.class.new(
         klass:, name:, output_schema: @output_schema, predicate: @predicate, fallback: @fallback,
-        validator: @validator, squawk: @squawk,
+        validator: @validator, squawk: @squawk, squawk_on: @squawk_on,
         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))
+        harness: call_harness || @harness, budget: @budget.merge(call_budget),
+        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
 
@@ -60,7 +68,7 @@ module Squishling
 
     # The system prompt: the purpose, then each append_to_purpose section.
     def purpose(receiver)
-      value = @purpose || klass.purpose
+      value = declared_purpose
       value = receiver.instance_exec(&value) if value.is_a?(Proc)
       return value if value.nil? || value.empty?
 
@@ -77,14 +85,48 @@ module Squishling
     end
 
     # 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.
-    def escalation_path
+    # or escalation, or a single attempt on the adapter'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. Models
+    # tied on priority are rotated by this method's call count (see Rotation). Steps whose include_when: is falsy
+    # for this call's inputs are left out, so a tier rotates only between its eligible models. advance: false looks
+    # at the turn the next call will get without counting this one (a prompt preview).
+    def escalation_path(receiver, inputs, advance: true)
+      declared, provider = declared_path
+      eligible = ModelPath.eligible(declared, receiver, inputs, label)
+      # Counted when the declared path rotates (so a call that excludes some models doesn't skew the others'
+      # rotation) or when this call's eligible steps do (an excluded rotate: false step no longer pins its tier).
+      rotates = ModelPath.rotating?(declared) || ModelPath.rotating?(eligible)
+      turn = if rotates
+        advance ? Rotation.advance(klass, name) : Rotation.peek(klass, name)
+      else
+        0
+      end
+      ModelPath.steps(eligible, provider:, params:, turn:)
+    end
+
+    # The steps and provider of the first level (method, class, or config) that declares a model or escalation, or
+    # the default step, before any call's include_when: filtering.
+    def declared_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, forward_rejected: true }]
-      ModelPath.steps(entries, provider:, params:)
+      [entries || [DEFAULT_STEP], provider]
+    end
+
+    # Whether a purpose is declared for this method or its class (a Proc one can't be evaluated without a receiver).
+    def purpose_declared?
+      value = declared_purpose
+      value.is_a?(Proc) || !(value.nil? || value.empty?)
+    end
+
+    # The names the method's inputs are sent under (see #bind_arguments), and whether any keyword may be an input:
+    # there is no implementation to name them, it takes **, or has a parameter with no name to send it under.
+    def input_names
+      names = parameters.filter_map { |type, param| input_name(type, param) }
+      any_keyword = !implemented? || parameters.any? do |type, param|
+        type == :keyrest || (Squawk::POSITIONAL_TYPES.include?(type) && param.nil?)
+      end
+      [names, any_keyword]
     end
 
     # How the escalation is used (see Harness): the method's, the class's, the configured default, or :escalation.
@@ -97,23 +139,48 @@ module Squishling
       Params.resolve(Squishling.config.default_params, klass.squishling_params, @params)
     end
 
+    # The token limits of one call (see Budget): config defaults, overridden limit by limit by the class, then by the
+    # method (and a squish! call).
+    def budget
+      Budget.resolve(Squishling.config.default_budget, klass.squishling_budget, @budget)
+    end
+
     # Extra output checks run on schema-valid LLM results (see ClassMethods#squish_validate).
     def validator
       @validator || klass.squishling_validator
     end
 
+    # The squish_fallback handler: the method's, else the class's (nil when there is none).
+    def fallback
+      @fallback || klass.squishling_fallback
+    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
 
+    # Which attempts reach the hook (see Squawk): the method's, else the class's, else the configured one.
+    def squawk_on
+      [@squawk_on, klass.squishling_squawk_on, Squishling.config.squawk_on].find { |on| !on.nil? }
+    end
+
     def context_names
       klass.squishling_context_names
     end
 
+    # The squish_when predicate: the method's, else the class's.
+    def predicate
+      @predicate || klass.squishling_predicate
+    end
+
+    # Whether the method has a Ruby implementation (otherwise every call goes to the LLM).
+    def implemented?
+      !Wrapper.implementation(klass.instance_method(name)).nil?
+    end
+
     def squish?(receiver, inputs)
-      predicate = @predicate || klass.squishling_predicate
       return false unless predicate
 
       receiver.instance_exec(**inputs, &predicate) ? true : false
@@ -124,7 +191,7 @@ module Squishling
     def invoke_llm(receiver, inputs)
       Invoker.new(self, receiver, inputs).call
     rescue InvalidOutputError, LLMError => e
-      handler = @fallback || klass.squishling_fallback
+      handler = fallback
       raise unless handler
 
       Squishling.config.logger&.warn("[Squishling] #{label} LLM failed, using fallback: #{e.message}")
@@ -144,7 +211,7 @@ module Squishling
 
       attrs = attrs.to_h if attrs.is_a?(Result::Instance)
       data, errors = jsonify_return(attrs)
-      errors = schema.validate(data) if errors.empty?
+      errors = InvalidOutputError::Detail.from(schema.validate(data), :schema) if errors.empty?
       raise InvalidOutputError.new(errors:, raw: attrs, source: "Deterministic") if errors.any?
 
       schema.build(data, squished:)
@@ -170,7 +237,7 @@ module Squishling
             unnamed += 1
           end
         when :rest
-          bound[param.nil? || param == :* ? :args : param] = positional.shift(positional.size)
+          bound[input_name(type, param)] = positional.shift(positional.size)
         end
       end
       positional.each_with_index { |value, index| bound[:"arg#{unnamed + index}"] = value }
@@ -184,7 +251,18 @@ module Squishling
     def jsonify_return(attrs)
       [Schema.jsonify(attrs), []]
     rescue JSON::GeneratorError, JSON::NestingError => e
-      [nil, [e.message]]
+      [nil, [InvalidOutputError::Detail.new(e.message, :parse)]]
+    end
+
+    def declared_purpose
+      @purpose || klass.purpose
+    end
+
+    def input_name(type, param)
+      case type
+      when :req, :opt, :key, :keyreq then param
+      when :rest then param.nil? || param == :* ? :args : param
+      end
     end
 
     # The implementation's parameters, beneath the prepended wrappers.

data/lib/squishling/errors.rb

@@ -7,27 +7,95 @@ module Squishling
   # missing API key). Never retried and never passed to squish_fallback.
   class ConfigurationError < Error; end
 
+  # The provider answered a request with HTTP 400 (or another 4xx that isn't a credentials, model, or redirect
+  # problem). Still a ConfigurationError: never retried, escalated, or passed to a fallback. The provider's message is
+  # never repeated; the machine-readable status and code its error body carries are, when they are plain tokens
+  # (e.g. "INVALID_ARGUMENT", "invalid_request_error"). Both are nil when the body has none.
+  class RequestRejectedError < ConfigurationError
+    attr_reader :provider_status, :provider_code
+
+    def initialize(message, provider_status: nil, provider_code: nil)
+      @provider_status = provider_status
+      @provider_code = provider_code
+      super(message)
+    end
+  end
+
+  # Squishling.verify! found problems in the squished classes' setup. report holds them all (see Verification::Report).
+  class VerificationError < ConfigurationError
+    attr_reader :report
+
+    def initialize(report)
+      @report = report
+      super(report.to_s)
+    end
+
+    def problems
+      report.problems
+    end
+  end
+
   # Output that didn't match the schema (or a squish_validate check): from the LLM after every attempt in the
   # escalation, or from the deterministic path.
   class InvalidOutputError < Error
-    # models: the model ids tried, one per attempt (nil entries mean RubyLLM's default model).
-    attr_reader :errors, :raw, :attempts, :models
+    # Added to the message (and the log line) when the last reply was cut off at the output token cap.
+    CUTOFF_NOTE = "cut off at the output token limit"
+
+    # One entry of #error_details: the message and where it came from.
+    #   :schema      a JSON Schema error; it can name a key the model chose (a disallowed additional property)
+    #   :validator   your own squish_validate message, verbatim (so it holds model values only if you interpolate them)
+    #   :parse       a message about a response or return value that didn't parse (not valid JSON, empty,
+    #                a value JSON can't represent)
+    #   :squishling  any other text Squishling or a custom harness wrote
+    Detail = Data.define(:message, :source) do
+      # One detail per message, all from the same source.
+      def self.from(messages, source) = messages.map { |message| new(message, source) }
 
-    def initialize(errors:, raw: nil, source: "LLM", attempts: nil, models: nil)
-      @errors = errors
+      def initialize(message:, source:)
+        unless Detail::SOURCES.include?(source)
+          raise ArgumentError, "unknown error source #{source.inspect} (expected #{Detail::SOURCES.join(', ')})"
+        end
+
+        super
+      end
+
+      # Whether the message can contain text the model chose, so a sink with its own control syntax should escape
+      # it. Your own squish_validate messages are never flagged, even if you interpolate result values into them.
+      def model_derived? = source == :schema
+    end
+    Detail::SOURCES = %i[schema validator parse squishling].freeze
+
+    # models: the model ids tried, one per attempt (nil entries mean the adapter's default model). finish_reason: why
+    # the provider stopped on the last attempt (a Symbol such as :stop or :max_tokens; nil when unknown or not from
+    # an LLM).
+    # errors: Strings, or Details; a String counts as :squishling text.
+    attr_reader :errors, :error_details, :raw, :attempts, :models, :finish_reason
+
+    def initialize(errors:, raw: nil, source: "LLM", attempts: nil, models: nil, finish_reason: nil)
+      @error_details = errors.map { |error| error.is_a?(Detail) ? error : Detail.new(error.to_s, :squishling) }
+      @error_details.freeze
+      @errors = @error_details.map(&:message).freeze
       @raw = raw
       @attempts = attempts
       @models = models
+      @finish_reason = finish_reason
       tries = attempts ? " after #{attempts} attempt#{'s' unless attempts == 1}" : ""
-      super("#{source} output was invalid#{tries}: #{errors.join('; ')}")
+      cutoff = " (#{CUTOFF_NOTE})" if truncated?
+      super("#{source} output was invalid#{tries}: #{@errors.join('; ')}#{cutoff}")
+    end
+
+    # Whether the last reply was cut off at the output token cap, so raising max_output_tokens (leaving room for any
+    # thinking budget) is the fix rather than changing the prompt or validator.
+    def truncated?
+      finish_reason == :max_tokens
     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.
+  # 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
 
@@ -44,7 +112,24 @@ module Squishling
     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.
+  # The call spent its token budget (max_total_output_tokens or max_total_input_tokens) before any attempt was
+  # accepted, so no further request was made. limit names the budget that was reached, max its value, and used the
+  # tokens spent so far ({ input_tokens:, output_tokens: }). errors starts with the budget line, then the validation
+  # errors of the last rejected output, which is in raw (nil when no output had been rejected, e.g. the samples were
+  # valid but the judge could not run). Like any InvalidOutputError it goes to squish_fallback.
+  class BudgetExhaustedError < InvalidOutputError
+    attr_reader :limit, :max, :used
+
+    def initialize(limit:, max:, used:, errors: [], raw: nil, attempts: nil, models: nil)
+      @limit = limit
+      @max = max
+      @used = used
+      spent = used.fetch(:"#{limit.to_s.delete_prefix('max_total_')}")
+      super(errors: ["token budget exhausted: #{spent} of #{max} #{limit} used", *errors], raw:, attempts:, models:)
+    end
+  end
+
+  # The LLM call itself failed (rate limit, server error, timeout, connection) after the
+  # adapter's own HTTP retries. The original exception is available as #cause.
   class LLMError < Error; end
 end