squishling 0.2.0 → 0.4.0

data/docs/naming.md

@@ -0,0 +1,43 @@
+# Naming and collisions
+
+`include Squishling` adds a small set of methods to your class. This page lists them and explains what happens
+when one of those names is already taken.
+
+## What Squishling adds
+
+| Where | Names |
+|---|---|
+| Class-level DSL | `squishling`, `purpose`, `append_to_purpose`, `output_schema`, `squish`, `squish_when`, `squish_fallback`, `squish_validate`, `squish_context`, `squished_methods`, `call`, and the `squishling_*` readers |
+| Instance | `squishling_result`, `squish!`, and `result` (an alias for `squishling_result`) |
+
+Methods your class defines itself always win over these, whether you define them before or after the `include`.
+Only methods your class *inherits* can be shadowed.
+
+## Inherited collisions raise
+
+If a parent class or an earlier-included module already defines a class-level DSL method, `squish!` or
+`squishling_result`, `include Squishling` raises `Squishling::ConfigurationError` listing every clash and where
+it comes from:
+
+```
+ConfigurationError: MyApp inherits methods that Squishling would override: MyApp.call (from Sinatra::Base's
+class methods). Include Squishling in a plain Ruby class instead ...
+```
+
+This is deliberate. Squishling's modules sit ahead of inherited ones, so without the check
+`Sinatra::Base.call(env)` (the Rack entry point), or any `call` or `purpose` your parent class defines, would be
+replaced silently. Put Squishling in a plain Ruby class and have your framework object call it instead.
+
+## `result` is skipped when taken
+
+`result` is a convenience for `squishling_result`. If the class already has a `result` (its own or inherited), it is
+left alone and Squishling does not add the alias. Use `squishling_result(...)` instead; it is always available.
+
+**ActiveRecord caveat.** Column readers are generated lazily, so Squishling can't see a `result` column when you
+include it. Its `result` would then shadow the column reader. On a model with a `result` column, call
+`squishling_result` (or keep Squishling out of the model and use a plain class).
+
+## Not a collision
+
+ActiveSupport adds `String#squish` and `String#squish!`. Those live on `String`; Squishling's `squish!` lives on
+your class, so they never meet. They only look alike when reading code in a Rails app.

data/docs/observers.md

@@ -0,0 +1,80 @@
+# Observers
+
+An observer wraps every provider request Squishling makes, so another tool can see it while it happens: open a
+tracing span, tag the request, set a thread-local. It is the around-style counterpart to [`squawk`](failures.md#observing-every-attempt-squawk),
+which reports each attempt only after it is over.
+
+Squishling ships one, for [Coolhand Labs](coolhand.md), and uses it automatically when the `coolhand` gem is configured.
+Any object that responds to `around(call)` is an observer:
+
+```ruby
+class TracingObserver
+  def around(call)
+    Tracer.in_span("squishling #{call.label}", attributes: { "model" => call.model, "role" => call.role.to_s }) do
+      yield
+    end
+  end
+end
+
+Squishling.configure { |config| config.observer = TracingObserver.new }
+```
+
+`around` must yield exactly once. The block makes the request, so the observer runs around it, on the thread that
+makes it: for the concurrent samples of the squishsum harnesses, that is a worker thread, so thread-locals set by the
+observer are visible to the HTTP call. What `around` returns is ignored. One that never yields, or yields twice,
+raises `ConfigurationError`.
+
+## What `yield` returns
+
+The block returns a `Squishling::Observer::Usage`: the request's `input_tokens` and `output_tokens` (nil when the
+provider didn't report them) and the `model` that answered. That is enough to meter spend:
+
+```ruby
+class SpendObserver
+  def around(call)
+    usage = yield
+    Metrics.increment("squishling.tokens.in", usage.input_tokens.to_i, tags: ["label:#{call.label}"])
+    Metrics.increment("squishling.tokens.out", usage.output_tokens.to_i, tags: ["label:#{call.label}"])
+  end
+end
+```
+
+Usage never includes the model's output; Squishling returns the real response to its own caller, whatever `around`
+returns. If the request fails, the error is raised through `yield`, so a `begin/ensure` in `around` still runs.
+
+## `config.observer`
+
+| Value | Meaning |
+|---|---|
+| `nil` (default) | The Coolhand observer when `coolhand` is loaded and configured, otherwise none |
+| `:coolhand` | The Coolhand observer, always. Raises `ConfigurationError` if the gem is missing or too old |
+| any object responding to `around` | That observer |
+| `false` | None, even when Coolhand is configured |
+
+Anything else raises `ConfigurationError` when you assign it.
+
+## The `call`
+
+`around` receives a `Squishling::Observer::Call` (a `Data`) describing the request:
+
+| Field | |
+|---|---|
+| `label` | `"Class#method"` |
+| `purpose` | The purpose text sent as the system prompt (after `purpose` procs and `append_to_purpose` sections are resolved) |
+| `handed_off` | `true` when a `squish!` call sent the call to the LLM (typically from a `rescue`), `false` when `squish_when` or a missing implementation did |
+| `harness` | The harness type (`:escalation`, `:squishsum`, `:judged_squishsum`, or a [custom one](harnesses.md#custom-harnesses)) |
+| `role` | `nil` for an escalation attempt, `:sample` or `:judge`, as in `squawk`'s `metadata` |
+| `sample` | `"a"`, `"b"`, ... for a sample, else `nil` |
+| `attempt`, `attempts` | This request's 1-based position in the steps it was asked on, and how many there are: the escalation's expanded steps (or, for a custom harness, those passed to `run.escalate`), the sample's stage, or the judge's steps |
+| `model`, `provider` | The step's model and provider (`provider` is `nil` unless declared) |
+| `request` | `:chat`, or `:judgment` for a System One judge |
+
+It carries metadata only. The method's inputs, its context, and the model's output never reach an observer: it gets
+the request's token [`Usage`](#what-yield-returns) back, and `squawk` is the route for output.
+
+## Errors
+
+An observer is your code: an exception it raises propagates unchanged, and is never retried, escalated, or handed to
+`squish_fallback`. Squishling maps a failed request onto `LLMError` or `ConfigurationError` inside the block, so `around` sees those and
+can rescue them or let them pass. If `around` rescues one and returns normally, Squishling raises it again: an
+observer can watch a failure, not swallow it.

data/docs/routing.md

@@ -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,10 +86,11 @@ 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:` or `escalation:`, `provider:`, and `params:` (generation params; see [Configuration](configuration.md))
+- `harness:` (see [Harnesses](harnesses.md), including your own)
 - `when:`, a predicate proc
 - `validate:` and `fallback:` (see [Failure handling](failures.md))
 
@@ -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 |
+| `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,11 +210,15 @@ Source is read with Ruby's own parser (Prism) the first time it's needed and cac
   "context":   { "customer_tier": "enterprise", "product": "API" } }
 ```
 
+- **Squishsum 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. Don't put data in those messages that you wouldn't send as an argument.
+  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,

data/docs/schemas.md

@@ -30,6 +30,23 @@ output_schema(
 )
 ```
 
+## Describing fields
+
+Every DSL type, and `optional`, takes a `description:`. It is sent to the provider as guidance for that field
+and isn't enforced; validation is by type and shape only.
+
+**Best practice:** put per-field guidance here rather than in the `purpose`. The description travels with the
+field in the schema the model fills in, so the instruction sits right where the value goes and next to the type
+or `enum` it explains. The purpose can then stay short and about the goal. For rules that must hold, use an
+`enum` or `squish_validate`; a description is a request, not a guarantee.
+
+```ruby
+output_schema do
+  string :language, description: "Lowercase language name, e.g. 'ruby'."
+  optional(:regex, description: "The proposed regex source, without delimiters or flags.") { string }
+end
+```
+
 ## Strict schemas only
 
 Squishling only supports **strict** output schemas: it always asks RubyLLM for strict structured output, and a
@@ -59,7 +76,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
 
@@ -69,7 +87,7 @@ field nullable with the DSL's `optional`. The key stays required, but its value
 ```ruby
 output_schema do
   array :symptoms, of: :string      # always a list; [] means "none"
-  optional :allergies do            # [] means "none", nil means "not mentioned"
+  optional :allergies, description: "[] if the record says none; null if it doesn't mention allergies" do
     array of: :string
   end
   optional :vitals do               # a typed Data object, or nil
@@ -83,8 +101,8 @@ end
 `optional` produces `anyOf: [<schema>, {type: "null"}]`, which is strict-compatible. Squishling types the non-null
 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.
+values come back as plain hashes. If you need the model to tell "none" apart from "not mentioned", say so in the field's
+`description:`, as `allergies` does above.
 
 ## Contracts beyond the schema
 
@@ -110,7 +128,8 @@ Providers' strict modes don't support conditional keywords (`if`/`then`/`else` f
 `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 instructions too.
+up front, so state them in the `description:` of the field they govern (here `status`) or in your purpose. A
+description declared inside a `given` block is local-only too, so it is never sent.
 
 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,27 +6,49 @@ module Squishling
     DEFAULT_METHOD = :call
 
     # Set class-wide options in one call:
-    #   squishling model: "claude-sonnet-5-5", instructions: "...", output_schema: MySchema
+    #   squishling model: "claude-sonnet-5-5", purpose: "...", output_schema: MySchema
     # model: is a single attempt; escalation: is a list of models tried in order (see ModelPath):
     #   squishling escalation: [{ model: "claude-haiku-4-5", attempts: 2 }, "claude-sonnet-5-5", "claude-opus-5-5"]
     # Pass provider: alongside model: for models missing from RubyLLM's registry, e.g.
-    #   squishling model: "gpt-6-luna", provider: :openai
+    #   squishling model: "gpt-7-preview", provider: :openai
+    # provider: needs a model: or escalation: (declared on the class), and a subclass's model never inherits its
+    # parent's provider.
     # params: are generation params merged over the configured defaults (see Configuration#default_params):
     #   squishling params: { temperature: 0.1, top_p: 0.9 }
-    # append_instructions: adds sections after the instructions (see #append_instructions):
-    #   squishling append_instructions: ["The Ruby that handles well-formed input:", self]
-    def squishling(model: nil, escalation: nil, provider: nil, params: nil, instructions: nil,
-      append_instructions: nil, output_schema: nil)
+    # append_to_purpose: adds sections after the purpose (see #append_to_purpose):
+    #   squishling append_to_purpose: ["The Ruby that handles well-formed input:", self]
+    # harness: chooses how the escalation is used (see Harness):
+    #   squishling harness: :judged_squishsum
+    # squawk: is called after every LLM attempt with the raw output (see Configuration#squawk); false silences
+    # an inherited one:
+    #   squishling squawk: ->(output:, metadata:, error:) { Tracer.record(output, metadata, error) }
+    def squishling(model: nil, escalation: nil, provider: nil, params: nil, harness: nil, purpose: nil,
+      append_to_purpose: nil, output_schema: nil, squawk: nil)
       path = ModelPath.declare(model, escalation, to_s)
+      # A provider belongs to the model declared at the same level. Without a model here it would apply to
+      # nothing (the model comes from the config or a parent class), so it is an error unless this class already
+      # declared its own.
+      if provider && !path && !instance_variable_defined?(:@squishling_model_path)
+        raise ConfigurationError, "#{self}: provider: needs a model: or escalation: declared on this class"
+      end
+
+      # Stored (even as nil) whenever a model is, so a subclass that declares its own model never inherits a
+      # provider meant for its parent's.
       @squishling_model_path = path if path
-      @squishling_provider = provider if provider
+      @squishling_provider = provider if provider || path
       @squishling_params = Params.normalize(params, "#{self} params") if params
-      self.instructions(instructions) if instructions
-      self.append_instructions(append_instructions) unless append_instructions.nil?
+      @squishling_harness = Harness.normalize(harness, to_s) unless harness.nil?
+      self.purpose(purpose) if purpose
+      self.append_to_purpose(append_to_purpose) unless append_to_purpose.nil?
       self.output_schema(output_schema) if output_schema
+      @squishling_squawk = Squawk.validate(squawk, to_s) unless squawk.nil?
       self
     end
 
+    def squishling_squawk
+      squishling_lookup(:@squishling_squawk)
+    end
+
     # The class's (or nearest ancestor's) model or escalation, as normalized steps.
     def squishling_model_path
       squishling_lookup(:@squishling_model_path)
@@ -36,33 +58,37 @@ module Squishling
       squishling_lookup(:@squishling_provider)
     end
 
+    def squishling_harness
+      squishling_lookup(:@squishling_harness)
+    end
+
     # Generation params merged down the inheritance chain, so a subclass overrides individual keys.
     def squishling_params
       squishling_inherited(:squishling_params, {}).merge(@squishling_params || {})
     end
 
     # The system prompt. A String, or a Proc evaluated against the instance.
-    def instructions(text = nil, &block)
-      return squishling_lookup(:@squishling_instructions) if text.nil? && block.nil?
+    def purpose(text = nil, &block)
+      return squishling_lookup(:@squishling_purpose) if text.nil? && block.nil?
 
-      @squishling_instructions = block || text
+      @squishling_purpose = block || text
     end
 
-    # Sections appended to the system prompt after the instructions, added to by subclasses, `squish`, and
+    # Sections appended to the system prompt after the purpose, added to by subclasses, `squish`, and
     # `squish!`. Items: Strings; a class or module (`self` for this class) or a method (`instance_method(:call)`),
     # sent as its Ruby source; or a Proc evaluated against the instance. `false` drops inherited items.
-    #   append_instructions "Here is the Ruby that parses well-formed invoices:", self
-    #   append_instructions { "This client's invoices are in #{currency}." }
-    def append_instructions(*items, &block)
+    #   append_to_purpose "Here is the Ruby that parses well-formed invoices:", self
+    #   append_to_purpose { "This client's invoices are in #{currency}." }
+    def append_to_purpose(*items, &block)
       items = items.first if items.size == 1 && items.first.is_a?(Array)
       items += [block] if block
-      (@squishling_append_instructions ||= []).concat(Appendices.normalize(items, "#{self} append_instructions"))
+      (@squishling_append_to_purpose ||= []).concat(Appendices.normalize(items, "#{self} append_to_purpose"))
       self
     end
 
     # Every level's items in declaration order, `false` markers included (see Appendices.resolve).
-    def squishling_append_instructions
-      squishling_inherited(:squishling_append_instructions, []) + (@squishling_append_instructions || [])
+    def squishling_append_to_purpose
+      squishling_inherited(:squishling_append_to_purpose, []) + (@squishling_append_to_purpose || [])
     end
 
     # The output format: a Schematist::Schema subclass (RubyLLM::Schema with the ruby_llm-schema shim),
@@ -85,7 +111,7 @@ module Squishling
 
     # Called with the error and the method's inputs (as keywords) when the LLM path fails with an
     # InvalidOutputError or LLMError, evaluated against the instance. Its return value is used as
-    # the result (hashes are validated and typed); re-raise to propagate.
+    # the result (validated against the schema and typed like a deterministic return); re-raise to propagate.
     #   squish_fallback { |error, **inputs| { priority: "medium", team: "support" } }
     def squish_fallback(&block)
       @squishling_fallback = block
@@ -118,21 +144,26 @@ module Squishling
     end
 
     # Make methods elastic. Each may override the class-level settings:
-    #   squish :triage, instructions: "...", escalation: %w[claude-haiku-4-5 claude-sonnet-5-5], when: ->(**) { true },
-    #                   fallback: ->(error, **) { { priority: "medium" } }, append_instructions: [...],
-    #                   validate: ->(result, **) { "team is required" if result.team.empty? } do
+    #   squish :triage, purpose: "...", escalation: %w[claude-haiku-4-5 claude-sonnet-5-5], when: ->(**) { true },
+    #                   fallback: ->(error, **) { { priority: "medium" } }, append_to_purpose: [...],
+    #                   validate: ->(result, **) { "team is required" if result.team.empty? },
+    #                   harness: :squishsum, squawk: ->(output:, error:, **) { Tracer.record(output, error) } do
     #     string :priority
     #   end
-    def squish(*names, instructions: nil, append_instructions: nil, output_schema: nil, model: nil, escalation: nil,
-      provider: nil, params: nil, when: nil, fallback: nil, validate: nil, &schema_block)
+    def squish(*names, purpose: nil, append_to_purpose: nil, output_schema: nil, model: nil, escalation: nil,
+      provider: nil, params: nil, harness: nil, when: nil, fallback: nil, validate: nil, squawk: nil, &schema_block)
       schema = schema_block ? Schematist::Schema.create(&schema_block) : output_schema
       model = ModelPath.declare(model, escalation, "#{self} squish")
+      raise ConfigurationError, "#{self} squish: provider: needs a model: or escalation:" if provider && !model
+
       params &&= Params.normalize(params, "#{self} squish params")
-      unless append_instructions.nil?
-        append_instructions = Appendices.normalize(append_instructions, "#{self} squish append_instructions")
+      harness = Harness.normalize(harness, "#{self} squish") unless harness.nil?
+      unless append_to_purpose.nil?
+        append_to_purpose = Appendices.normalize(append_to_purpose, "#{self} squish append_to_purpose")
       end
-      options = { instructions:, append_instructions:, output_schema: schema, model:, provider:, params:,
-                  predicate: binding.local_variable_get(:when), fallback:, validator: validate }.compact
+      squawk = Squawk.validate(squawk, "#{self} squish")
+      options = { purpose:, append_to_purpose:, output_schema: schema, model:, provider:, params:, harness:,
+                  predicate: binding.local_variable_get(:when), fallback:, validator: validate, squawk: }.compact
 
       names.map(&:to_sym).each do |name|
         (@squishling_methods ||= {})[name] = options

data/lib/squishling/collisions.rb

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

data/lib/squishling/configuration.rb

@@ -23,16 +23,33 @@ module Squishling
     # with_thinking; any other key (top_p, max_tokens, seed, ...) is passed to the provider as-is.
     attr_reader :default_params
 
+    # How every squishling class that doesn't declare its own harness uses its escalation (see Harness):
+    # :escalation (the default), :squishsum, :judged_squishsum, a harness you registered, or a Hash with type: and
+    # its options.
+    attr_reader :default_harness
+
     # Optional Logger for routing and escalation decisions.
     attr_accessor :logger
 
+    # Optional callable run after every LLM attempt with the raw output (see Squawk), e.g.
+    #   ->(output:, metadata:, error:) { Tracer.record(output, metadata, error) }
+    attr_reader :squawk
+
+    # 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
+
     def initialize
+      @observer = nil
       @default_model = nil
       @default_escalation = nil
       @default_model_path = nil
       @default_provider = nil
       @default_params = {}
+      @default_harness = nil
       @logger = nil
+      @squawk = nil
     end
 
     def default_model=(model)
@@ -47,10 +64,25 @@ module Squishling
       @default_escalation = escalation
     end
 
+    def squawk=(hook)
+      @squawk = Squawk.validate(hook, "Squishling.configure")
+    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
 
+    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 }]"