squishling 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0748f552c985521890d365ebc0818ec59c4336f93fb183d1769f49ed8cd32349'
-  data.tar.gz: '05128ecf8d7156e0c8ca084bf8a1860b754596017df2cdfdcc35e2242138fa7b'
+  metadata.gz: 0fb55da97a0a032802afcd90b8e56d497a42194206ad90f07d71bc46c70a9e49
+  data.tar.gz: 79430c869cda0726357c42c1ad1fdc7cbf9108a00ebcd56814df4e45acf99db6
 SHA512:
-  metadata.gz: 2be443b51d2dc1460a410fbf0850bed09e33fff5f7ad894d4bd92e3f47d428d22df7bfc0371036c090a6b806f466b1d930de3a9caf8d1b044185fd4000b765bf
-  data.tar.gz: 3a18d6e041f5807c966677fea5499de8af5d0f28146cb98bbe205141598ee6a01a2d598b1326df3b78227455dcc124c69cf95afacabf9a1689a1cc382a652414
+  metadata.gz: 95f83f1f99d86b5b2fddcc0d5e7d845aff73dbb7cc85620eafb93f999edd69181e8a72c726409cdb6ec11fa1286264947c48ac5f3467c1fb368755ef8ad95b62
+  data.tar.gz: 4ad6fbec6185bb9e4369c972b9f561bce840db75a96ba02c619fe82d1726e15230330b8f457c740017b08e412b3da2c364fd40f657db3128b28cab9c01ba993b

data/CHANGELOG.md

@@ -7,7 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.3.0] - 2026-10-09
+## [0.4.0] - 2026-10-18
+
+### Added
+
+- Custom harnesses: `Squishling.register_harness` (with `Squishling.harnesses` and `reset_harnesses!`) and
+  `Squishling::Harness::Base` let you write your own harness and use it anywhere a built-in works (`harness:`,
+  `squish!`, `default_harness`). A harness gets a `Squishling::Run` with `escalate`, `samples`, `judge`, `agree?`,
+  `stage`, and `log`, so it keeps model, provider, and params resolution, `squish_validate`, concurrent samples, and the
+  normal failure handling; it can only return typed results its `Run` produced, and its options are validated when it
+  is declared. The built-in `:escalation`, `:squishsum`, and `:judged_squishsum` now run on the same interface.
+  `squawk` metadata gains `role:` and `sample:`. See [Custom harnesses](docs/harnesses.md#custom-harnesses). (#31)
+- Round-robin models: escalation steps that share a `priority:` form a tier. Each call rotates which model in the tier
+  goes first (counted per class and method, shared across threads), and the tier's other models are tried before the
+  next priority. `rotate: false` on a step pins its tier to the order written. (#38)
+- `config.observer`: an around-style hook (`around(call) { ... }`) wrapped around every provider request, on the thread
+  that makes it, so a `:squishsum` sample's observer runs on its worker thread. It is told the request's `Observer::Call`
+  and gets back only an `Observer::Usage` (token counts and model), never the response. An observer that yields twice
+  or never raises `ConfigurationError`, and one that rescues the request's error has it raised again. See
+  [Observers](docs/observers.md). (#25, #40)
+- A bundled Coolhand observer (`observer = :coolhand`) that declares each call's workload (`Class#method`) and template
+  (`squish:L<n>`, `sample:a`, or `judge`) through `Coolhand.with_context`. The workload's description is
+  `Class#method`, or `Class#method (rescue)` when a `squish!` call handed the call to the LLM (`Observer::Call#handed_off`),
+  never the purpose text. It needs coolhand 0.9.0 or newer. See
+  [Coolhand Labs](docs/coolhand.md). (#40)
+- A docs page and landing-page section on the architecture, an explainer site in `site/` deployed to GitHub Pages, and
+  per-field `description:` documented as the best practice over `purpose` guidance. (#30, #33, #34, #36)
+
+### Changed
+
+- **Behavior change:** when the `coolhand` gem is loaded and configured (an API key, not disabled), Squishling now
+  declares each request's workload and template to it automatically. Nothing changes for apps without Coolhand. To
+  opt out, set `config.observer = false`.
+- **Behavior change:** two escalation steps may now share a `priority:` (they used to raise `duplicate order:`), and
+  they rotate per call as described above. If you relied on a fixed order between tied steps, give them distinct
+  priorities or set `rotate: false`.
+- `order:` on an escalation step is deprecated in favor of `priority:`. It still works, with a deprecation warning, and
+  giving both on one step raises `ConfigurationError`. Judge and harness steps take no `priority:` or `rotate:`. (#38)
+- **Behavior change:** `LLMError` and the `ConfigurationError` for a rejected request (400), bad credentials, or a
+  forbidden key no longer repeat the provider's own message, which can echo request content or part of an API key into
+  logs and error trackers. They carry the error class and HTTP status (`RubyLLM::RateLimitError, HTTP 429`); the
+  provider's message is still on `cause`. If you matched on provider text in `e.message`, read `e.cause.message`
+  instead.
+- `docs/measuring-tokens.md` now points to observers for bringing your own metrics instead of walking through a
+  hand-rolled one. (#40)
+
+### Removed
+
+- **Breaking change:** the `:ensemble` and `:judged_ensemble` harnesses added in 0.3.0 are gone. `harness: :ensemble`
+  or `:judged_ensemble` (and `default_harness`) now raise `ConfigurationError` (unknown harness). Use `:squishsum` or
+  `:judged_squishsum`, which sample the first escalation step twice with the judge defaulting to the next step, or
+  write a custom harness. (#22, #24)
+
+### Internal
+
+- CI gains an exhale duplication and complexity gate (`bin/exhale`), and dependabot bumps `rubocop` (1.92), `ruby/setup-ruby`,
+  and `actions/upload-artifact`. These are development-only changes. (#27, #28, #29, #41)
+
+## [0.3.0] - 2026-10-10
 
 ### Added
 

data/README.md

@@ -2,6 +2,10 @@
   <img src="assets/squishling-logo.png" alt="Squishling" width="420">
 </h1>
 
+<p align="center">
+  <strong><a href="https://coolhand-labs.github.io/squishling/">📖 Read the Squishling explainer →</a></strong>
+</p>
+
 [![CI](https://github.com/Coolhand-Labs/squishling/actions/workflows/ci.yml/badge.svg)](https://github.com/Coolhand-Labs/squishling/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/squishling.svg)](https://badge.fury.io/rb/squishling)
 
@@ -14,7 +18,17 @@ Either way it returns the same strict-schema-validated, typed result, so callers
 Think of code as a cache for AI judgment. Every line you write is something to maintain, so the LLM is the
 default and code has to earn its place: you build it for the inputs that carry the volume, and the LLM keeps
 handling the rest. New to the idea? Read
-[Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai).
+[Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai) or browse the
+[talk slides](https://michael.carroll.io/talks/2026/elastic-software/).
+
+Or try it on the [explainer site](https://coolhand-labs.github.io/squishling/):
+
+- [Spectrum slider](https://coolhand-labs.github.io/squishling/#spectrum): drag from traditional software to fully
+  LLM and see the tradeoff at each point
+- [Token-cost calculator](https://coolhand-labs.github.io/squishling/#number): price your tech debt in tokens
+  against code upkeep
+- [Walkthrough](https://coolhand-labs.github.io/squishling/#squishling): describe it, tune it, pay for accuracy,
+  harden the common shapes
 
 ## Use cases
 
@@ -81,6 +95,12 @@ Both calls return the same result class. If the LLM can't deliver either, `squis
 return, or the error is raised with the original `ParseError` as its cause. See
 [Handing off to the LLM](docs/routing.md#handing-off-to-the-llm-with-squish).
 
+### Retire code you no longer need
+
+Go the other way too. Find the parsers and handlers that serve a thin tail of your traffic and squish them. When a
+path's monthly token cost is lower than what its code costs to maintain, delete the code and relish the feeling of a
+slimmer code base (or let your AI coding agent relish it).
+
 ### Measure your tech debt in tokens
 
 Code you haven't written is debt you haven't taken on. A squished path has a running cost you can read off a
@@ -131,6 +151,11 @@ validated on both paths). A squished call goes to the LLM when:
 
 Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM output.
 
+**Best practice: describe fields in the schema, not the purpose.** Put per-field guidance in a `description:` on
+the field (`string :status, description: "..."`, or `optional(:eta, description: "...") { string }`). The model
+sees it right where the value goes, and the purpose stays short and about the goal. See
+[Describing fields](docs/schemas.md#describing-fields).
+
 ## Features
 
 - **One contract, two paths**: Ruby returns and LLM output are validated against the same strict schema and
@@ -140,7 +165,7 @@ Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM
 - **Any RubyLLM provider and model**: OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, OpenRouter, and more.
   Set a universal, per-class, per-method, or per-call model, plus layered generation params (temperature,
   reasoning effort, top_p, …).
-- **Model escalation**: declare an `escalation:` instead of a `model:`, with per-step `attempts:`, `order:`, provider,
+- **Model escalation**: declare an `escalation:` instead of a `model:`, with per-step `attempts:`, `priority:` (models tied on priority take turns going first), provider,
   params, and `forward_rejected:`. Invalid output (with its errors fed back) or a provider failure moves on to the next attempt. Steps can
   cross providers, e.g. a local Qwen model on Ollama, then Anthropic Claude Haiku on AWS Bedrock, then Claude Opus:
 
@@ -168,7 +193,8 @@ Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM
   - [`:escalation`](docs/configuration.md#models-and-escalation) (default): try each attempt until one passes
   - [`:squishsum`](docs/harnesses.md#samples): two concurrent samples, accepted only if they agree
   - [`:judged_squishsum`](docs/harnesses.md#the-judge): a chat or Jev judge picks between disagreeing samples
-  - [`:ensemble` and `:judged_ensemble`](docs/harnesses.md#ensembles): the same checks across two different models
+  - [Your own](docs/harnesses.md#custom-harnesses): `Squishling.register_harness` plugs a custom harness into the same
+    machinery (samples, judges, `squawk`, `squish_fallback`)
 - **Output contracts**: beyond the strict schema, conditional rules (`given`) and Ruby checks (`squish_validate`)
   reject bad output and trigger the next attempt.
 - **Defined failure behavior**: provider errors become `Squishling::LLMError`, and `squish_fallback` lets you decide
@@ -182,15 +208,19 @@ Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM
 
 ## Documentation
 
+- [Explainer site](https://coolhand-labs.github.io/squishling/): interactive walkthrough, spectrum slider, and
+  token-cost calculator
 - [Configuration](docs/configuration.md): options, models and escalation, providers, generation params, inheritance
 - [Routing](docs/routing.md): when a call goes to the LLM, `squish!`, `append_to_purpose`, hardening a path,
   what the LLM sees
 - [Output schemas](docs/schemas.md): schema forms, strict mode, typed results, optional vs. empty, contracts
 - [Failure handling](docs/failures.md): escalation, `squish_validate`, error classes, fallbacks
-- [Harnesses](docs/harnesses.md): escalation, squishsum, ensemble, and judges (chat or Jev)
+- [Harnesses](docs/harnesses.md): escalation, squishsum, judges (chat or Jev), and custom harnesses
 - [Naming and collisions](docs/naming.md): the methods `include Squishling` adds and what happens when a name is taken
 - [Measuring token spend](docs/measuring-tokens.md): see what each squished path costs, with Coolhand Labs,
-  the `squawk` hook, OpenTelemetry, LangSmith, or RubyLLM's instrumenter
+  the `squawk` hook, your own observer, or OpenTelemetry
+- [Observers](docs/observers.md): wrap every provider request, and the built-in [Coolhand Labs](docs/coolhand.md) observer
+  that files each call under its workload and template
 - [Live examples](examples/README.md): end-to-end tests against Anthropic Claude Haiku and OpenAI GPT-6 Luna
 
 ## Development
@@ -201,10 +231,12 @@ bundle exec rake        # RSpec (offline; RubyLLM is stubbed) + RuboCop
 ```
 
 See [AGENTS.md](AGENTS.md) for repo conventions, and [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
+Have a suggestion to improve Squishling? [Open an issue](https://github.com/Coolhand-Labs/squishling/issues).
 
 ## Credits
 
-Inspired by [Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai).
+Inspired by [Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai); see also
+the [talk slides](https://michael.carroll.io/talks/2026/elastic-software/) from XO Ruby NYC 2026.
 
 ## License
 

data/docs/configuration.md

@@ -29,7 +29,8 @@ end
 | `default_provider` | `nil` | The provider for `default_model`/`default_escalation` steps that don't name one. Only needed for models missing from RubyLLM's registry (see below). |
 | `default_params` | `{}` | Generation params for every call (temperature, reasoning effort, top_p, …), overridable per class, per method, and per escalation step. See [Generation params](#generation-params). |
 | `squawk` | `nil` | A callable run after every LLM attempt with the raw output, for sending it to an error tracker or tracing tool. Also settable per class and per method. See [Observing every attempt](failures.md#observing-every-attempt-squawk). |
-| `default_harness` | `nil` (`:escalation`) | How every squishling class that doesn't declare its own uses its escalation: `:escalation`, `:squishsum`, `:judged_squishsum`, `:ensemble`, `:judged_ensemble`, or a Hash with `type:` and options. See [Harnesses](harnesses.md). |
+| `observer` | `nil` | An around-style hook for every provider request: `:coolhand`, any object responding to `around(call)`, or `false` for none. `nil` uses the [Coolhand observer](coolhand.md) when the `coolhand` gem is configured. See [Observers](observers.md). |
+| `default_harness` | `nil` (`:escalation`) | How every squishling class that doesn't declare its own uses its escalation: `:escalation`, `:squishsum`, `:judged_squishsum`, a [registered custom harness](harnesses.md#custom-harnesses), or a Hash with `type:` and options. See [Harnesses](harnesses.md). |
 | `logger` | `nil` | Any `Logger`. Debug lines when a call routes to the LLM, warnings on each escalation and when a fallback is used. Never includes the raw model response; see [what ends up in errors and logs](failures.md#what-ends-up-in-errors-and-logs). |
 
 Transport-level retries (rate limits, 5xx, timeouts) are configured on RubyLLM itself
@@ -62,21 +63,50 @@ Each step is a model name, or a Hash with:
 |---|---|---|
 | `model:` | required | The model id. |
 | `attempts:` | `1` | How many attempts this step gets before escalating to the next one. |
-| `order:` | position | An Integer; steps run lowest first. Give every step an `order:` or none (duplicates are rejected). Gaps are fine. |
+| `priority:` | position | An Integer; steps run lowest first. Give every step a `priority:` or none. Steps with the same priority are one tier (see [Rotating models](#rotating-models-within-a-priority)). Gaps are fine. `order:` is the deprecated name for it. |
+| `rotate:` | `true` | Set `false` on a step to keep its tier in the order written instead of rotating it. |
 | `provider:` | the level's `provider:` | See [Providers](#providers-and-newly-released-models). |
 | `forward_rejected:` | `true` | Set `false` to start this step from the original input alone, without the previous step's rejected output and its errors (see below). |
 | `params:` | `{}` | [Generation params](#generation-params) for this step, merged over the class and method params key by key. |
 
-Without `order:`, steps run in the order written. With it, the order is explicit and doesn't depend on position:
+Without `priority:`, steps run in the order written. With it, the order is explicit and doesn't depend on position:
 
 ```ruby
 squishling escalation: [
-  { model: "claude-opus-5-5",   order: 20, params: { thinking: { effort: :high } } },
-  { model: "claude-haiku-4-5",  order: 0, attempts: 2 },
-  { model: "claude-sonnet-5-5", order: 10 }
+  { model: "claude-opus-5-5",   priority: 30, params: { thinking: { effort: :high } } },
+  { model: "claude-haiku-4-5",  priority: 10, attempts: 2 },
+  { model: "gemma-4b",          priority: 10 },
+  { model: "claude-sonnet-5-5", priority: 20 }
 ]
 ```
 
+**Best practice:** number priorities 10, 20, 30, and so on, so a model can be slotted in between later (a `15`)
+without renumbering the rest. Haiku and Gemma share the lowest priority here, so they take turns going first (see below).
+
+### Rotating models within a priority
+
+Give several models the same `priority:` and they share a tier. Each call rotates which of them goes first, so
+every model gets an even share of the real work over many calls, a fair test of how well each handles it:
+
+```ruby
+squishling escalation: [
+  { model: "claude-haiku-4-5",  priority: 10 },
+  { model: "gemma-4b",          priority: 10 },
+  { model: "claude-sonnet-5-5", priority: 20 }
+]
+# call 1: haiku, gemma-4b, sonnet    call 2: gemma-4b, haiku, sonnet    call 3: haiku, gemma-4b, sonnet
+```
+
+- If the model that goes first fails (invalid output or a provider failure, after its own `attempts:`), the other
+  models in the tier are tried, in rotated order, before the call escalates to the next priority.
+- Each class and method counts its own calls (`AClass#a`, `AClass#b` and `BClass#a` rotate independently), shared across
+  threads, but not across processes: each process (a Puma worker, say) starts its own count at the first model, and it
+  restarts with the process. A `squish!` whose own escalation has a rotating tier counts against its method too.
+- A tier rotates by its declared order, so ties keep the order they were written in. A tier with a single model
+  never rotates, and neither does an escalation without `priority:`. `rotate: false` on any step of a tier keeps the
+  whole tier in the order written, whatever its other steps say.
+- Rotation also moves which stages the [`:squishsum` and `:judged_squishsum`](harnesses.md) harnesses sample first.
+
 `params:` on a step let one step switch to a reasoning model that rejects sampling params:
 
 ```ruby

data/docs/coolhand.md

@@ -0,0 +1,66 @@
+# Coolhand Labs
+
+Squishling ships an [observer](observers.md) for [Coolhand Labs](https://coolhandlabs.com/). With it, every LLM call a
+squished method makes is filed under a named **workload** and **template** in Coolhand. Squishling knows exactly
+where each call sits (which method, which escalation level, which sample, which judge), so it declares that for you.
+
+## Setup
+
+Add and configure the [`coolhand`](https://github.com/Coolhand-Labs/coolhand-ruby) gem as described in
+[Measuring token spend](measuring-tokens.md#coolhand-labs). **That's all.** Squishling defaults to the Coolhand
+observer whenever Coolhand is already available in your codebase: loaded, with an `api_key`, and not disabled
+(`config.enabled = false`). Nothing is added to Squishling's dependencies, and nothing happens when the gem isn't
+there. It needs a version of the `coolhand` gem that has `Coolhand.with_context` (declared workloads); with an older
+one, the observer stays off.
+
+To turn it off, set `observer` to `false`:
+
+```ruby
+Squishling.configure do |config|
+  config.observer = false # never declare, even though Coolhand is configured
+end
+```
+
+The other settings:
+
+```ruby
+Squishling.configure do |config|
+  config.observer = :coolhand # always declare; raises ConfigurationError now if the gem is missing or too old
+  config.observer = nil       # the default: declare when Coolhand is loaded and configured
+end
+```
+
+To report somewhere else, or as well, use any [other observer](observers.md). `config.observer` holds one.
+
+## What is declared
+
+Each request runs inside `Coolhand.with_context(reporter: "squishling", workload: ..., template: ...)`, so Coolhand's
+Net::HTTP interception tags it with the declaration.
+
+| | Key | Name |
+|---|---|---|
+| Workload | `Class#method` | `Class#method` (its `description` is `Class#method`, or `Class#method (rescue)` when a [`squish!`](routing.md#handing-off-to-the-llm-with-squish) call handed it to the LLM) |
+| Template | `Class#method/<role>` | `Class#method · <role>` |
+
+`<role>` is where the request sits:
+
+| Role | Request |
+|---|---|
+| `squish:L<n>` | Attempt *n* (1-based) of the [escalation](configuration.md#models-and-escalation), counting each attempt of each step (a [custom harness](harnesses.md#custom-harnesses) that escalates stage by stage restarts at L1 for each) |
+| `sample:a`, `sample:b`, ... | A [squishsum](harnesses.md) sample (which runs on a worker thread; the declaration is made on that thread) |
+| `judge` | A harness's judge, chat or System One (all of a judge's attempts share this one template) |
+
+So `Parser#call/squish:L2` is the second attempt of `Parser#call`, e.g. `Parser#call · squish L2` in Coolhand.
+
+- The model is deliberately not in the key. It is on the log, and the position is the stable identity.
+- Repeated attempts on the same step count as separate levels, because the level is the attempt's position in the
+  expanded escalation.
+- A class name long enough to push a key past Coolhand's 255-character limit is left undeclared rather than
+  breaking the call.
+- Squishling's declaration is made inside any `Coolhand.with_context` you wrapped around the call, so for the fields it
+  sets, Squishling's wins.
+- The description never contains the purpose text, which can be a proc that differs per call. The workload's key
+  and name stay `Class#method` either way, so calls that went through `squish!` and calls that didn't share one
+  workload.
+- `observer = :coolhand` loads the gem when it is assigned, so assign it after `coolhand` is available (the default
+  needs no ordering).

data/docs/failures.md

@@ -10,12 +10,12 @@ A failed attempt moves on to the next one; once the last fails, the error is rai
 |---|---|
 | Rate limit, 5xx, overload, timeout, connection error | RubyLLM retries at the HTTP level first (`RubyLLM.config.max_retries`, default 3). If it still fails, moves to the next attempt in a fresh chat; on the last attempt, raises `Squishling::LLMError` with the original exception as its `cause`. |
 | Bad API key, unknown model, missing provider config | Raises `Squishling::ConfigurationError`. Never escalated, never sent to the fallback. |
-| Provider rejects the request (400 Bad Request), e.g. an unsupported `temperature` or a schema it won't accept | Raises `ConfigurationError` with the provider's message and the params in use. Never escalated, never sent to the fallback, so a setup mistake can't be silently covered up on every call. |
+| Provider rejects the request (400 Bad Request), e.g. an unsupported `temperature` or a schema it won't accept | Raises `ConfigurationError` naming the error class and HTTP status, and the params in use; the provider's own message is on `cause`. Never escalated, never sent to the fallback, so a setup mistake can't be silently covered up on every call. |
 | Empty or `nil` response (e.g. a refusal or a max-tokens cutoff) | Moves to the next attempt, then raises `Squishling::InvalidOutputError` |
 | Malformed or truncated JSON | Moves to the next attempt, then raises `InvalidOutputError`. JSON wrapped in a markdown code fence is accepted. |
 | JSON that doesn't match the schema (wrong types, missing or extra keys, `null` in a non-`optional` field, a broken [conditional rule](schemas.md#contracts-beyond-the-schema), root not an object) | Moves to the next attempt with the validation errors, then raises `InvalidOutputError` |
 | Schema-valid output that [`squish_validate`](#output-checks-squish_validate) rejects | Moves to the next attempt with your messages, then raises `InvalidOutputError` |
-| With a [squishsum or ensemble harness](harnesses.md): two valid samples that differ, with no judge or a judge that rejects both | Raises `Squishling::DisagreementError` (an `InvalidOutputError`), carrying both typed `candidates` |
+| With a [squishsum harness](harnesses.md): two valid samples that differ, with no judge or a judge that rejects both | Raises `Squishling::DisagreementError` (an `InvalidOutputError`), carrying both typed `candidates` |
 
 Squishling validates output itself with [json_schemer](https://github.com/davishmcclurg/json_schemer), because
 RubyLLM doesn't, and some providers don't enforce strict mode. When the next attempt is on the same step (same
@@ -42,6 +42,9 @@ Model output can echo sensitive input, so the raw response is kept in one place:
   the message, the logger, and the next attempt's prompt.
 - A fixed message when a response contains a value JSON can't represent (`1e400` parses to `Infinity`, or a string
   with invalid UTF-8).
+- For a failed provider request (`LLMError`, and the `ConfigurationError` for a 400, bad credentials, or a forbidden
+  key), only the error class and HTTP status. The provider's own message can echo request content or part of an API
+  key, so it stays on `cause` (`error.cause.message`) for you to read or log deliberately.
 - At most the first 20 of these errors, plus a count of the rest, so a very large malformed response can't flood
   the retry message or the log.
 - For a [`DisagreementError`](harnesses.md#when-the-harness-fails), only what Squishling wrote: a `:judgment` judge's
@@ -69,7 +72,7 @@ end
 |---|---|
 | `output` | The raw response: a Hash or String, or `nil` when the provider call itself failed |
 | `error` | `nil` for an accepted attempt. Otherwise the `InvalidOutputError` (with `errors` and `raw`) or `LLMError` that ended the attempt |
-| `metadata` | `label` (`"Class#method"`), `attempt`, `attempts` (the escalation's length; under a harness, the sample's or judge's own attempts), `final` (the last attempt), `model`, `provider`, `params`, `input` (the JSON sent: arguments and named context only), `usage` (token counts, when RubyLLM reports them) |
+| `metadata` | `label` (`"Class#method"`), `attempt`, `attempts` (the escalation's length; under a harness, the sample's or judge's own attempts), `final` (the last attempt), `model`, `provider`, `params`, `input` (the JSON sent: arguments and named context only), `usage` (token counts, when RubyLLM reports them), `role` (`nil` for an escalation attempt, `:sample`, or `:judge`), `sample` (`"a"`, `"b"`, ... for a sample's attempt, else `nil`) |
 
 - Set it globally with `config.squawk`, per class with `squishling squawk: ...`, or per method with
   `squish :triage, squawk: ...`. The method's hook wins over the class's, which wins over the configured one;
@@ -79,7 +82,8 @@ end
 - It runs inline, so keep it quick. Exceptions it raises propagate unchanged and fail the call, like any of your own
   code, so rescue inside the hook if an outage in your tracing tool shouldn't.
 - `output` is the same object the result is built from, so treat it as read-only.
-- Under a [harness](harnesses.md), it runs for every sample and judge attempt too, each with its own `input`.
+- Under a [harness](harnesses.md), it runs for every sample and judge attempt too, each with its own `input`, and
+  `role`/`sample` say which one it was. A [custom harness](harnesses.md#reporting-to-squawk) reports the same way.
 - It isn't called for a `ConfigurationError`, for deterministic and fallback returns, or for an attempt where your own
   `squish_validate` raises (that exception propagates first).
 
@@ -118,7 +122,7 @@ end
 | `Squishling::Error` | Base class for everything below. Raised directly for misuse at call time, e.g. `result` or `squish!` called outside a squished method |
 | `Squishling::ConfigurationError` | Missing purpose or schema, a non-strict schema, invalid or reserved params, an invalid `model:`/`escalation:` declaration, an invalid `append_to_purpose` item or unavailable source, bad credentials, an unknown model, a request the provider rejects (400) |
 | `Squishling::InvalidOutputError` | LLM output still invalid (schema or `squish_validate`) after every attempt in the escalation, or a deterministic/fallback return that doesn't match the schema |
-| `Squishling::DisagreementError` | A subclass of `InvalidOutputError`: a [squishsum or ensemble harness](harnesses.md#when-the-harness-fails)'s samples disagreed and no judge accepted either. `candidates`, `verdict`, and `reason` describe what happened |
+| `Squishling::DisagreementError` | A subclass of `InvalidOutputError`: a [squishsum harness](harnesses.md#when-the-harness-fails)'s samples disagreed and no judge accepted either. `candidates`, `verdict`, and `reason` describe what happened |
 | `Squishling::LLMError` | The provider call failed on the last attempt in the escalation, after RubyLLM's own retries, including context-length errors (`cause` holds the original) |
 
 Errors raised by your own Ruby code are not wrapped.