squishling 0.2.0 → 0.3.0

data/docs/harnesses.md

@@ -0,0 +1,198 @@
+# Harnesses: escalation, squishsum, and ensemble
+
+A squished call's **harness** decides how it uses its [escalation](configuration.md#models-and-escalation):
+
+| Harness | What it does | Requests per call |
+|---|---|---|
+| `:escalation` (default) | Tries each attempt in order until an output passes the schema and `squish_validate`. | 1 or more |
+| `:squishsum` | Asks the escalation's **first step** twice, concurrently. Identical outputs are accepted; different ones raise `Squishling::DisagreementError`. | 2 or more |
+| `:judged_squishsum` | Like `:squishsum`, but when the two outputs differ, a **judge** picks one or rejects both. | 2 or more, plus 1 or more judge requests when they differ |
+| `:ensemble` | Asks the escalation's **first and second steps** once each, concurrently, so two different models are compared. Identical outputs are accepted; different ones raise `DisagreementError`. | 2 or more |
+| `:judged_ensemble` | Like `:ensemble`, but when the two outputs differ, a **judge** picks one or rejects both. | 2 or more, plus 1 or more judge requests when they differ |
+
+Use a squishsum harness when a confidently wrong answer costs more than a second request: one sample can make a
+mistake, but two independent samples rarely make the same one. Use an [ensemble](#ensembles) when the two samples
+should come from different models: a model rarely disagrees with itself at low temperature, but a cheap and a
+stronger model often disagree on exactly the cases the cheap one gets confidently wrong.
+
+```ruby
+class TicketTriager
+  include Squishling
+
+  squishling escalation: [{ model: "claude-haiku-4-5", attempts: 2 }, "claude-sonnet-5-5"],
+             harness: :judged_squishsum   # two Haiku samples; Sonnet judges when they differ
+  purpose "Assign a priority and a team."
+  output_schema do
+    string :priority, enum: %w[low medium high]
+    string :team
+  end
+end
+```
+
+## Declaring a harness
+
+`harness:` takes a type, or a Hash with `type:` and its options:
+
+```ruby
+Squishling.configure { |c| c.default_harness = :squishsum }      # every class without its own
+
+squishling harness: :judged_squishsum                            # this class (and subclasses)
+squish :triage, harness: { type: :squishsum,                     # one method
+                           compare: ->(a, b, **) { a.priority == b.priority } }
+squish!(harness: :escalation)                                    # one call (see routing.md)
+```
+
+The first level that declares one wins: `squish!`, then the method, then the class, then
+`Squishling.config.default_harness`, then `:escalation`. Options aren't merged across levels.
+
+| Option | Harnesses | Description |
+|---|---|---|
+| `type:` | all | `:escalation`, `:squishsum`, `:judged_squishsum`, `:ensemble`, or `:judged_ensemble` (required in the Hash form). |
+| `compare:` | squishsum and ensemble ones | `->(a, b, **inputs) { ... }`, evaluated against the instance with the two typed results and the method's inputs. Truthy means the samples agree. Default: the two outputs are exactly equal. |
+| `judge:` | judged ones | The judge step (see [The judge](#the-judge)). Default: the escalation's next step after the sampled ones. |
+| `judge_instructions:` | judged ones | A String, or a Proc evaluated against the instance, that replaces the [default judge prompt](#the-default-judge-prompt). |
+
+## Samples
+
+Under `:squishsum`, both samples run on the escalation's first step, with its model, provider, and params
+(an [ensemble](#ensembles) runs them on its first and second steps):
+
+- **They're independent.** Each sample has its own chat, and the two requests are sent concurrently on separate
+  threads. Only the provider requests run on those threads. Parsing, schema validation, `squish_validate`,
+  `compare:`, and the judge all run on the calling thread, so your Squishling callbacks never run concurrently.
+  RubyLLM instrumentation subscribers (e.g. `ActiveSupport::Notifications` listeners for `chat.ruby_llm`) do see
+  each sample's request on its worker thread, outside the Rails executor, so keep them thread-safe.
+- **Each one is retried like an escalation step.** A sample with invalid output is re-asked in its own chat, up to
+  their step's `attempts:`, while a sample that already passed keeps its result. A failed request gets a fresh
+  chat. A sample still failing after its attempts fails the call with `InvalidOutputError` or `LLMError`, as
+  usual. Under `:squishsum`, later escalation steps are never used for samples (see [Ensembles](#ensembles)).
+- **Agreement is exact by default.** Free-text fields seldom match word for word, so pass `compare:` to decide
+  which fields must match:
+
+  ```ruby
+  squishling harness: { type: :squishsum, compare: ->(a, b, **) { a.priority == b.priority && a.team == b.team } }
+  ```
+
+  When the samples agree, the first one is returned.
+
+## Ensembles
+
+`:ensemble` and `:judged_ensemble` sample two *different* steps instead of one step twice. Sample `a` is the
+escalation's first step and sample `b` its second, each with its own model, provider, and params:
+
+```ruby
+class TicketTriager
+  include Squishling
+
+  squishling escalation: [{ model: "claude-haiku-4-5", attempts: 2 }, "claude-sonnet-5-5", "claude-opus-5-5"],
+             harness: :judged_ensemble   # a = Haiku, b = Sonnet, Opus judges when they differ
+  # purpose, output_schema, ...
+end
+```
+
+- A step's `attempts:` are that sample's retries (here Haiku gets two attempts, Sonnet one), exactly as in
+  [Samples](#samples). Steps after the second are never sampled.
+- Everything else matches squishsum: independence and concurrency, `compare:`, `DisagreementError`, and the
+  judge. `DisagreementError#models` names the model behind each sample.
+- The judge defaults to the escalation's **third** step. With only two steps, a `:judged_ensemble` needs `judge:`.
+  An ensemble with fewer than two steps, or a judged one with neither a third step nor `judge:`, raises
+  `ConfigurationError` before any request.
+- A global `default_harness = :ensemble` therefore needs every class to declare at least two steps, and a
+  `squish!(model: ...)` override (one step) can't be combined with an ensemble harness.
+- Steps are told apart by value, so two adjacent steps with the same model, provider, and params count as one step.
+
+## The judge
+
+With a judged harness, two valid samples that disagree go to a judge. The judge picks candidate `a` or `b`,
+whose typed result is returned (`squished?` is `true`), or it picks `neither`, which raises
+`DisagreementError`.
+
+The judge is:
+
+1. the `judge:` step, if declared: a model name, or a Hash with `model:`, `provider:`, `params:`, and `attempts:`
+   (as in an escalation step, without `order:`), plus `type:`; or
+2. the escalation's next step after the sampled ones (the second under `:judged_squishsum`, the third under
+   `:judged_ensemble`), with its attempts.
+
+A judged harness with neither raises `ConfigurationError` before any sample is requested. A `judge:`
+step uses only its own `provider:`; it doesn't inherit the class or method `provider:`, which belongs to their models
+(a chat judge's params, though, do merge over the method's).
+
+### Chat judges
+
+By default the judge is a chat model, asked for a strict `{ "verdict": "a" | "b" | "neither", "reason": "..." }`.
+It gets the same context the samples had, plus the samples themselves:
+
+- **System prompt:** the judge prompt, then the operation's own purpose (including any `append_to_purpose`
+  sections).
+- **User message:** JSON with the samples' `input` (`arguments` and `context`), the `output_schema`, and the
+  `candidates` `a` and `b`.
+
+A verdict that doesn't match its schema is retried per the judge step's `attempts:`; a judge that never returns a
+valid verdict raises `InvalidOutputError`. A chat judge's params are the method's
+[generation params](configuration.md#generation-params) with its own `params:` merged over them.
+
+### System One judgment models (Jev)
+
+A judge can also be a System One decision model, such as TypeSafe's Jev, via
+[RubyLLM judgments](https://rubyllm.com/judgments/) (RubyLLM 2.1+). Decision models return calibrated
+probabilities rather than text, so they are much faster and cheaper than a chat judge.
+
+```ruby
+squishling harness: {
+  type: :judged_squishsum,
+  judge: { model: "jev-latest", type: :judgment, min_confidence: 0.8 }
+}
+```
+
+Squishling asks one `choice` question (`a`, `b`, or `neither`), with the judge prompt as its instructions and the
+operation's purpose, input, output schema, and candidates as the judgment input. A pick of `a` or `b` is
+accepted only when its probability is at least `min_confidence:` (default `0.8`). Otherwise, as with `neither`,
+`DisagreementError` is raised with the choice and its probability in its `reason`. A judgment judge sends only its own
+`params:` (as RubyLLM `provider_options:`). `attempts:` retries a failed request. Configure the provider's
+credentials in RubyLLM as usual.
+
+### The default judge prompt
+
+```text
+You are an impartial judge. Two independent attempts at the same operation returned different outputs,
+candidate "a" and candidate "b". Both already match the required output format, so judge only their
+content. You are given the operation's purpose and its input. Decide which candidate correctly and
+faithfully carries out the purpose for this input. If both do (for example, they differ only in
+wording), choose either one, preferring "a". Choose "neither" only when both are wrong or you can't tell
+whether either is correct. Never combine them or invent a third answer.
+```
+
+It is available as `Squishling::Harness::DEFAULT_JUDGE_INSTRUCTIONS`. Replace it with `judge_instructions:`:
+
+```ruby
+squishling harness: { type: :judged_squishsum,
+                      judge_instructions: "Pick the candidate whose priority follows our SLA rules: ..." }
+```
+
+## When the harness fails
+
+A disagreement raises `Squishling::DisagreementError`, a subclass of `InvalidOutputError`. It's raised when the
+samples differ with no judge, or when the judge rejects both. Like any failure on the LLM path, it goes to
+[`squish_fallback`](failures.md#fallbacks), which can still return one of the candidates:
+
+```ruby
+squish_fallback do |error, **|
+  raise error unless error.is_a?(Squishling::DisagreementError)
+
+  error.candidates.first   # already typed and validated; squished? is true
+end
+```
+
+| Attribute | Value |
+|---|---|
+| `candidates` | The two typed results, `[a, b]` |
+| `verdict` | `nil` when there was no judge; `:neither` when the judge rejected both |
+| `reason` | The judge's reason (or, for a judgment model, the choice and its probability). A chat judge's reason is model-written, so it is not part of `message` or the logs; a judgment model's choice and probability are |
+| `raw` | Both candidates as Hashes, `[a.to_h, b.to_h]` |
+| `attempts` | `nil` |
+| `models` | The model behind each role: sample `a`, sample `b`, then the judge if one ran (one entry each, not one per attempt) |
+
+Other failures are unchanged. A sample or judge that never produces valid output raises `InvalidOutputError`, a
+failed request on the last attempt raises `LLMError`, and setup mistakes (including a provider 400 on either
+sample) raise `ConfigurationError`, which is never sent to the fallback.

data/docs/measuring-tokens.md

@@ -0,0 +1,148 @@
+# Measuring token spend
+
+A squished path costs tokens on every call. A Ruby path costs engineer time once, plus upkeep. Measuring the
+first tells you when the second is worth paying.
+
+## What Squishling gives you
+
+- `result.squished?` says which path served a call, so you can count LLM calls per class.
+- The [`squawk` hook](failures.md#observing-every-attempt-squawk) runs after every LLM attempt and receives the
+  method (`label`, e.g. `"ShipmentUpdate#call"`), the model and provider, which attempt it was, and the token usage
+  RubyLLM reported. That is enough to attribute spend to a squishling method without any other tooling.
+- Cost in dollars comes from RubyLLM's model pricing. Multiply the reported tokens by your model's price, or read it
+  from RubyLLM directly (see [the instrumenter](#lower-level-rubyllms-instrumenter)).
+
+## Deciding when to write the code
+
+For each squished path, over a month:
+
+```
+token cost  =  calls × (input tokens × input price + output tokens × output price)
+code cost   =  time to write it  +  upkeep  (new cases, format changes, on-call)
+```
+
+Write the Ruby when the token cost keeps exceeding the code cost, and narrow `squish_when` so only the inputs
+Ruby can't handle still go to the LLM. See [Hardening a path](routing.md#hardening-a-path). If the token cost
+stays small, the debt you haven't taken on is cheaper than the code.
+
+## Tools
+
+| Option | Good for | Setup |
+|---|---|---|
+| [Coolhand Labs](#coolhand-labs) | Picking up your squishling calls automatically and measuring their cost and accuracy | The `coolhand` gem and an initializer |
+| [Custom: the `squawk` hook](#custom-the-squawk-hook) | Logging or metrics in your own stack, with no new dependency | A lambda and one config line |
+| [OpenTelemetry](#opentelemetry) | Sending traces to Datadog, Langfuse, Arize, Braintrust, LangSmith, or any OTel backend | The OpenTelemetry SDK, an exporter, and one line |
+| [LangSmith](#langsmith) | Browsing traces and token usage in LangSmith | Through OpenTelemetry |
+
+### Coolhand Labs
+
+Add and initialize the [`coolhand`](https://github.com/Coolhand-Labs/coolhand-ruby) gem. It intercepts the LLM
+requests your app makes, so it picks up your squishling calls automatically and measures their cost, and their
+accuracy through Coolhand's feedback tools. No changes to your squishling classes.
+
+```ruby
+# Gemfile
+gem "coolhand"
+
+# config/initializers/coolhand.rb
+Coolhand.configure do |config|
+  config.api_key = ENV.fetch("COOLHAND_API_KEY")
+end
+```
+
+Get an API key at [coolhandlabs.com](https://coolhandlabs.com/). To keep the data in your own infrastructure, point
+`config.base_url` at a Coolhand-compatible endpoint of your own.
+
+### Custom: the `squawk` hook
+
+`config.squawk` runs after every LLM attempt, accepted or rejected, and is handed the method's label, the model,
+and the token usage RubyLLM reported. A lambda can take just the keywords it needs:
+
+```ruby
+Squishling.configure do |config|
+  config.squawk = lambda do |metadata:, **|
+    usage = metadata[:usage] || {}   # nil when the provider call failed; counts it didn't report are absent
+    Rails.logger.info("squishling #{metadata[:label]} model=#{metadata[:model]} " \
+                      "attempt=#{metadata[:attempt]}/#{metadata[:attempts]} " \
+                      "in=#{usage[:input_tokens]} out=#{usage[:output_tokens]}")
+  end
+end
+```
+
+Each line carries the `"Class#method"` that made the call, so grouping by label gives you tokens per squishling. A call
+that stays in Ruby makes no LLM request and never reaches the hook, so a label that stops appearing is a path that has
+been hardened. You can also set the hook per class (`squishling squawk: ...`) or per method. See
+[Observing every attempt](failures.md#observing-every-attempt-squawk) for every keyword and the rules for exceptions.
+
+### Lower level: RubyLLM's instrumenter
+
+To meter every RubyLLM request in your app, not only Squishling's, use RubyLLM's own instrumentation. It reports a
+`usage.ruby_llm` event for each provider request, with `model`, `provider`, `status`, `tokens` (`input`, `output`,
+and more) and `cost`. Give it an object that responds to `instrument(name, payload)` and optionally takes a block. In
+Rails, `ActiveSupport::Notifications` is used automatically.
+
+```ruby
+class TokenMeter
+  def instrument(name, payload = {})
+    if name == "usage.ruby_llm"
+      Rails.logger.info("llm model=#{payload[:model]} workflow=#{payload[:workflow_name]} " \
+                        "in=#{payload[:tokens].input} out=#{payload[:tokens].output}")
+    end
+    block_given? ? yield : nil
+  end
+end
+
+RubyLLM.configure { |config| config.instrumenter = TokenMeter.new }
+```
+
+These events don't know which squishling made the request. To attribute the spend, wrap the call in a RubyLLM
+workflow, and every event emitted inside the block carries its name, id and any `metadata:` you pass. (The
+`squawk` hook above needs no wrapping.)
+
+```ruby
+RubyLLM.workflow("ShipmentUpdate", metadata: { carrier: "acme-freight" }) do
+  ShipmentUpdate.call(carrier: "acme-freight", payload: body)
+end
+```
+
+### OpenTelemetry
+
+RubyLLM 2.1+ ships its own OpenTelemetry tracer. Each request becomes a span with the model, request settings and
+token usage (`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`), following the OpenTelemetry GenAI
+conventions. It does not record message text. Your app owns the SDK and exporters.
+
+```ruby
+# Gemfile
+gem "opentelemetry-sdk"
+gem "opentelemetry-exporter-otlp"   # or your backend's exporter
+
+# config/initializers/opentelemetry.rb
+OpenTelemetry::SDK.configure        # reads the standard OTEL_* environment variables
+RubyLLM::OpenTelemetry.enable       # starts tracing RubyLLM requests
+```
+
+Spans don't say which squishling made the request, so pair this with a `RubyLLM.workflow` (see
+[above](#lower-level-rubyllms-instrumenter)) or group by model and prompt in your backend.
+
+### LangSmith
+
+LangSmith accepts OpenTelemetry traces, so the OpenTelemetry setup above covers it: point the OTLP exporter at
+LangSmith. See LangSmith's
+[OpenTelemetry docs](https://docs.smith.langchain.com/observability/how_to_guides/tracing/trace_with_opentelemetry)
+for the endpoint and headers. A community Ruby gem, [`langsmith-sdk`](https://github.com/felipekb/langsmith-ruby-sdk),
+also exists; it isn't published by LangChain.
+
+## Privacy
+
+Squishling only sends the model what you name: the method arguments, any `squish_context` values, and any source you
+append. Tools that sit on the request path are a separate route out of your process, and they see both sides:
+
+- **Request interceptors, such as `coolhand`,** record the prompts (your purpose text and those inputs) and the
+  model's responses. Coolhand sends them to coolhandlabs.com unless you point `config.base_url` at an endpoint of your
+  own.
+- **A `squawk` hook that forwards `output:` or `metadata[:input]`** sends model output and your inputs wherever you
+  send them. That is the sanctioned route for model output; see
+  [Observing every attempt](failures.md#observing-every-attempt-squawk). The examples above log only metadata.
+- **OpenTelemetry** with RubyLLM's tracer records usage and request settings, not message text.
+
+Check what your tool stores before pointing it at inputs that contain personal data.

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/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))
 - `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 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. 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

@@ -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,7 +85,7 @@ 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
 
@@ -110,7 +111,7 @@ 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 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