squishling 0.1.0 → 0.3.0

data/docs/routing.md

@@ -18,7 +18,7 @@ A squished call runs its Ruby implementation unless one of these sends it to the
 |---|---|---|
 | `squish_when` (or `when:`) predicate is truthy | class, or per method | before Ruby runs |
 | The method has no implementation: it isn't defined, or it raises `NotImplementedError` | the method body | when Ruby gives up |
-| `squish!` | inside the method, e.g. in a `rescue` | after Ruby has partly run, see [Escalating from Ruby](#escalating-from-ruby-with-squish) |
+| `squish!` | inside the method, e.g. in a `rescue` | after Ruby has partly run, see [Handing off to the LLM](#handing-off-to-the-llm-with-squish) |
 
 With no predicate and a working implementation, every call runs Ruby.
 
@@ -35,24 +35,27 @@ end
 def summarize(text) = raise NotImplementedError   # elastic until someone writes it
 ```
 
-When the Ruby implementation runs, a `Hash` it returns is validated against the schema and turned into the
-same typed result the LLM path produces. `result(...)` (alias `squishling_result`) does the same explicitly.
-Invalid deterministic output raises `Squishling::InvalidOutputError` too, so a hardened path can't silently
-drift from the contract.
+When the Ruby implementation runs, whatever it returns (a `Hash`, `nil`, a string, another schema's result, …)
+is validated against the schema and turned into the same typed result the LLM path produces.
+`squishling_result(...)` does the same explicitly; `result(...)` is a convenience alias, skipped when the class
+already has a `result` (see [Naming and collisions](naming.md)). Invalid deterministic output raises
+`Squishling::InvalidOutputError` too, so a hardened path can't silently drift from the contract.
 
 A `NotImplementedError` raised anywhere inside the method, including from code it calls, also routes to the
 LLM.
 
-Each call is routed on its own, including a squished method that calls itself on smaller inputs. A subclass
+Each call is routed on its own, including a squished method that calls itself on smaller inputs (those
+recursive calls must return schema-valid values too). A subclass
 override that calls `super` is one call: it's routed once, at the subclass. A call to the method from its own
-`squish_when` or `squish_fallback` (or an instructions proc) isn't routed again: it runs the Ruby
-implementation, so a fallback can hand the input back to Ruby with `call(**inputs)`.
+`squish_when` or `squish_fallback` (or a purpose proc) isn't routed again: it runs the Ruby
+implementation, so a fallback can hand the input back to Ruby with `call(**inputs)`. These inner calls
+return a `Hash` as the typed result and any other value unchanged; only the outermost return is validated in full.
 
 ## Hardening a path
 
 This is the workflow from [Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai):
 
-1. Ship the class with instructions and a schema but no implementation. Every call goes to the LLM.
+1. Ship the class with purpose and a schema but no implementation. Every call goes to the LLM.
 2. Watch which inputs carry the volume. `squished?` on each result tells you which path served it.
 3. Write Ruby for the high-volume cases and narrow `squish_when` so only the rest go to the LLM.
 
@@ -68,7 +71,7 @@ class TicketTriager
 
   squish_context :customer_tier, :product   # instance state sent alongside the arguments
 
-  squish :triage, instructions: "Assign a priority and team.", model: "claude-haiku-4-5" do
+  squish :triage, purpose: "Assign a priority and team.", model: "claude-haiku-4-5" do
     string :priority, enum: %w[low med high]
     string :team
   end
@@ -83,16 +86,17 @@ end
 
 `squish` accepts:
 
-- `instructions:` (replaces the class's)
-- `append_instructions:` (added to the class's, see [Appending to the instructions](#appending-to-the-instructions))
+- `purpose:` (replaces the class's)
+- `append_to_purpose:` (added to the class's, see [Appending to the purpose](#appending-to-the-purpose))
 - `output_schema:` (or a schema block)
-- `model:`, `provider:`, and `params:` (generation params; see [Configuration](configuration.md))
+- `model:` or `escalation:`, `provider:`, and `params:` (generation params; see [Configuration](configuration.md))
+- `harness:` (see [Harnesses](harnesses.md))
 - `when:`, a predicate proc
-- `fallback:` (see [Failure handling](failures.md))
+- `validate:` and `fallback:` (see [Failure handling](failures.md))
 
 `squish` can come before or after the method's `def`.
 
-## Escalating from Ruby with `squish!`
+## Handing off to the LLM with `squish!`
 
 Call `squish!` inside a squished method to hand *this call* to the LLM: for example, when the Ruby parser
 fails on an input it wasn't written for. It sends the call's arguments, as any LLM call would, and returns the
@@ -103,8 +107,8 @@ from the method.
 class InvoiceParser
   include Squishling
 
-  instructions "Extract invoice fields from the client's raw data."
-  append_instructions "Here is the Ruby that parses well-formed invoices, for context on the logic and goals:",
+  purpose "Extract invoice fields from the client's raw data."
+  append_to_purpose "Here is the Ruby that parses well-formed invoices, for context on the logic and goals:",
                       self
   output_schema do
     string :invoice_number
@@ -115,7 +119,7 @@ class InvoiceParser
     parsed = AcmeParser.parse(data)
     result(invoice_number: parsed.id, total: parsed.sum)
   rescue AcmeParser::ParseError => e
-    squish!(append_instructions: "The Ruby parser above failed on this input; the error is in the context.",
+    squish!(append_to_purpose: "The Ruby parser above failed on this input; the error is in the context.",
             context: { parse_error: e })
   end
 end
@@ -126,9 +130,10 @@ end
 | Option | Effect |
 |---|---|
 | `context:` | A Hash sent under `"context"` with any `squish_context` values (a same-named key wins). Exceptions are sent as `{ "class", "message" }`, never their backtrace. |
-| `append_instructions:` | Added to the declared sections; `false` (alone or first in an Array) drops them for this call |
-| `instructions:` | Replaces the instructions |
-| `model:`, `provider:`, `params:` | E.g. escalate to a stronger model when Ruby fails. A `provider:` needs a `model:`; `params:` merge key by key over the declared ones. |
+| `append_to_purpose:` | Added to the declared sections; `false` (alone or first in an Array) drops them for this call |
+| `purpose:` | Replaces the purpose |
+| `model:` or `escalation:`, `provider:`, `params:` | E.g. send this call to a stronger model, or a whole [escalation](configuration.md#models-and-escalation), when Ruby fails. A `provider:` needs a `model:` or `escalation:`; `params:` merge key by key over the declared ones. |
+| `harness:` | Replaces the declared [harness](harnesses.md), e.g. `harness: :judged_squishsum` to double-check a hand-off |
 
 - **The output schema can't be overridden.** The call still returns the method's result type.
 - **Failures** go through the normal LLM path: a declared `squish_fallback` is used, otherwise
@@ -148,9 +153,9 @@ end
   or in a parent implementation reached through `super`. Calling it anywhere else, or from a `squish_fallback`
   (which would loop), raises `Squishling::Error`.
 
-## Appending to the instructions
+## Appending to the purpose
 
-`append_instructions` adds sections to the system prompt after the instructions. It takes items, an Array of
+`append_to_purpose` adds sections to the system prompt after the purpose. It takes items, an Array of
 them, or a block (treated as a Proc item). Each item is one of:
 
 | Item | Sent as |
@@ -164,19 +169,19 @@ them, or a block (treated as a Proc item). Each item is one of:
 class InvoiceParser
   include Squishling
 
-  append_instructions "The Ruby that parses well-formed invoices:", self, AcmeParser
-  append_instructions -> { "This client's invoices are in #{currency}." }
+  append_to_purpose "The Ruby that parses well-formed invoices:", self, AcmeParser
+  append_to_purpose -> { "This client's invoices are in #{currency}." }
 
-  squish :summarize, append_instructions: false do   # no appendices for this method
+  squish :summarize, append_to_purpose: false do   # no appendices for this method
     string :summary
   end
 end
 ```
 
-The same option goes in the class-wide call: `squishling append_instructions: ["...", self]`.
+The same option goes in the class-wide call: `squishling append_to_purpose: ["...", self]`.
 
-Sections are added down the chain: class, then subclass, then `squish :name, append_instructions:`, then
-`squish!(append_instructions:)`. `false` drops everything declared above it, so `[false, "Only this."]`
+Sections are added down the chain: class, then subclass, then `squish :name, append_to_purpose:`, then
+`squish!(append_to_purpose:)`. `false` drops everything declared above it, so `[false, "Only this."]`
 replaces it.
 
 Source is read with Ruby's own parser (Prism) the first time it's needed and cached. Some limits:
@@ -195,8 +200,8 @@ Source is read with Ruby's own parser (Prism) the first time it's needed and cac
 
 ## What the LLM sees
 
-- **System prompt:** your instructions (a String, or a Proc evaluated against the instance), then any
-  `append_instructions` sections, then a short note describing the input format.
+- **System prompt:** your purpose (a String, or a Proc evaluated against the instance), then any
+  `append_to_purpose` sections, then a short note describing the input format.
 - **User message:** JSON with the method's arguments, mapped to their parameter names. Any
   `squish_context` values, and a `squish!` call's `context:`, go under `"context"`:
 
@@ -205,6 +210,16 @@ Source is read with Ruby's own parser (Prism) the first time it's needed and cac
   "context":   { "customer_tier": "enterprise", "product": "API" } }
 ```
 
+- **Squishsum and ensemble harnesses:** both samples get exactly this input, and a [judge](harnesses.md#the-judge) gets
+  the same purpose and input plus both samples' outputs.
+- **Retries and escalation:** another attempt of the same step gets the validation errors in the same conversation. A
+  later [escalation](configuration.md#models-and-escalation) step, which may be a different provider (say, local
+  Ollama, then hosted Anthropic Claude), gets the same JSON plus the previous model's rejected output and the
+  errors, including any messages your [`squish_validate`](failures.md#output-checks-squish_validate) check
+  returned. The rejected output is model-generated and is truncated to 4,000 characters; set
+  `forward_rejected: false` on a step to start it from the original input only, without the rejected output or
+  its errors. Don't put data in those messages that you wouldn't send as an argument.
+
 `squish_context` names are read from a method of that name if there is one, otherwise from the instance
 variable. Only context you name is sent. Instance variables are never dumped wholesale, so API clients,
 database connections, and secrets stay out of the prompt.

data/docs/schemas.md

@@ -59,7 +59,8 @@ r.squished?                      # => true when it came from the LLM
 ```
 
 On the deterministic path, return a `Hash` or build the result with `result(...)`. Either way it's validated
-against the schema.
+against the schema, and so is anything else you return (`nil`, a string, another schema's result), which raises
+`Squishling::InvalidOutputError` unless it matches.
 
 ## Optional vs. empty
 
@@ -84,4 +85,33 @@ end
 branch as usual: `vitals` is a `Data` object or `nil`, and a list of objects is a list of `Data` objects. In a raw
 JSON Schema, `type: ["array", "null"]` works too. A union with more than one non-null branch is ambiguous, so its
 values come back as plain hashes. If you need the model to tell "none" apart from "not mentioned", say so in your
-instructions.
+purpose.
+
+## Contracts beyond the schema
+
+Every response is validated against the full schema, so some contracts are already enforced:
+
+- **A non-`optional` field can't be `null`.** `string :reason` rejects `"reason": null`. Make a field `optional` only
+  when "not provided" is a real answer.
+- **Constraints** such as `enum`, `min_length`, `pattern`, `minimum`, and `min_items` are checked locally, even where
+  a provider's strict mode ignores them.
+
+For rules that depend on another field, use Schematist's conditionals. A field can be nullable in general but
+required when a condition holds:
+
+```ruby
+output_schema do
+  string :status, enum: %w[approved rejected]
+  optional(:reason) { string }                                  # nil is fine when approved...
+  given(status: "rejected") { string :reason, min_length: 1 }   # ...but not when rejected
+end
+```
+
+Providers' strict modes don't support conditional keywords (`if`/`then`/`else` from `given`, and `dependentRequired`/
+`dependentSchemas` from `dependent`), so Squishling keeps them out of the schema it sends and enforces them itself.
+Output that breaks a rule is rejected like any other invalid output: the call moves on to the next attempt in its
+[escalation](configuration.md#models-and-escalation) with the errors. The model doesn't see these rules
+up front, so state them in your purpose too.
+
+For anything a schema can't express (sums, lookups against your data), use
+[`squish_validate`](failures.md#output-checks-squish_validate).

data/lib/squishling/appendices.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Squishling
-  # append_instructions: extra system-prompt sections placed after the instructions, layered
+  # append_to_purpose: extra system-prompt sections placed after the purpose, layered
   # class -> subclass -> method -> call. Each level adds to the levels above it; `false` drops them.
   module Appendices
     ITEM_TYPES = [String, Module, Method, UnboundMethod, Proc].freeze
@@ -29,7 +29,7 @@ module Squishling
 
         values = receiver.instance_exec(&item)
         (values.is_a?(Array) ? values : [values]).select(&:itself).map do |value|
-          check!(value, "#{label} append_instructions proc", procs: false)
+          check!(value, "#{label} append_to_purpose proc", procs: false)
           render_item(value)
         end
       end
@@ -43,7 +43,7 @@ module Squishling
       allowed = procs ? ITEM_TYPES : ITEM_TYPES - [Proc]
       return if allowed.any? { |type| item.is_a?(type) }
 
-      raise ConfigurationError, "#{label}: append_instructions items must be Strings, classes or modules, " \
+      raise ConfigurationError, "#{label}: append_to_purpose items must be Strings, classes or modules, " \
                                 "#{procs ? 'methods, or procs' : 'or methods'} (got #{describe(item)})"
     end
 

data/lib/squishling/class_methods.rb

@@ -6,59 +6,89 @@ 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, provider: nil, params: nil, instructions: nil, append_instructions: nil,
-      output_schema: nil)
-      @squishling_model = model if model
-      @squishling_provider = provider if provider
+    # 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 || 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_model
-      squishling_lookup(:@squishling_model)
+    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)
     end
 
     def squishling_provider
       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),
@@ -81,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
@@ -91,6 +121,19 @@ module Squishling
       squishling_lookup(:@squishling_fallback)
     end
 
+    # Extra checks on LLM output that already matches the schema, called with the typed result and the
+    # method's inputs (as keywords), evaluated against the instance. Return nil (or true, "", []) to accept,
+    # or error message(s) to reject the output and move on to the next attempt, with the messages fed back:
+    #   squish_validate { |result, **| "total must equal the line items" if result.total != result.line_items.sum }
+    # A dry-validation style result (responding to success? and errors) is accepted too.
+    def squish_validate(&block)
+      @squishling_validator = block
+    end
+
+    def squishling_validator
+      squishling_lookup(:@squishling_validator)
+    end
+
     # Instance state (attributes or instance variables) to send to the LLM alongside the arguments.
     def squish_context(*names)
       (@squishling_context_names ||= []).concat(names.map(&:to_sym))
@@ -101,19 +144,26 @@ module Squishling
     end
 
     # Make methods elastic. Each may override the class-level settings:
-    #   squish :triage, instructions: "...", model: "...", provider: :openai, when: ->(**) { true },
-    #                   fallback: ->(error, **) { { priority: "medium" } }, append_instructions: [...] 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, provider: nil,
-      params: nil, when: nil, fallback: 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: }.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

@@ -2,12 +2,20 @@
 
 module Squishling
   class Configuration
-    # Model used by every squishling class that doesn't declare its own.
-    # When nil, RubyLLM's own default model is used.
-    attr_accessor :default_model
+    # 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.
+    attr_reader :default_model
 
-    # Provider for default_model (e.g. :openai). Only needed for models missing from
-    # RubyLLM's registry.
+    # Models tried in order by every squishling class that doesn't declare its own, e.g.
+    #   [{ model: "claude-haiku-4-5", attempts: 2 }, "claude-sonnet-5-5", "claude-opus-5-5"]
+    # See ModelPath. default_model and default_escalation set the same thing: assigning one clears the other.
+    attr_reader :default_escalation
+
+    # 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.
     attr_accessor :default_provider
 
     # Generation params applied to every call, overridable per class and per method.
@@ -15,22 +23,63 @@ module Squishling
     # with_thinking; any other key (top_p, max_tokens, seed, ...) is passed to the provider as-is.
     attr_reader :default_params
 
-    # How many times to re-ask the LLM when its output fails schema validation.
-    attr_accessor :max_retries
+    # 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 decisions.
+    # 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 = {}
-      @max_retries = 1
+      @default_harness = nil
       @logger = nil
+      @squawk = nil
+    end
+
+    def default_model=(model)
+      @default_model_path = ModelPath.from_model(model, "default_model")
+      @default_escalation = nil
+      @default_model = model
+    end
+
+    def default_escalation=(escalation)
+      @default_model_path = ModelPath.from_escalation(escalation, "default_escalation")
+      @default_model = nil
+      @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 }]"
+
+    # Removed: the escalation decides how many attempts run.
+    def max_retries
+      raise ConfigurationError, MAX_RETRIES_REMOVED
+    end
+
+    def max_retries=(_value)
+      raise ConfigurationError, MAX_RETRIES_REMOVED
+    end
   end
 end