0.7.0: remove :adapter_error default retry, narrow AdapterCaller rescue

[justi]

Summary

0.7.0 — breaking changes targeting redundancy between ruby_llm-contract and upstream ruby_llm 1.14.1.

1. :adapter_error removed from DEFAULT_RETRY_ON. New default: [:validation_failed, :parse_error]. ruby_llm's Faraday middleware already retries transport errors (RateLimitError, ServerError, ServiceUnavailableError, OverloadedError, timeouts) with backoff (connection.rb:77), so the previous default re-ran the same model on errors the HTTP layer had already retried — retry × retry with no change in context. Opt in explicitly if needed, paired with escalate for meaningful model fallback.
2. AdapterCaller narrows rescue StandardError → rescue ::RubyLLM::Error. Programmer errors (NoMethodError, ArgumentError, config bugs) now propagate instead of being silently coerced into :adapter_error and retried. Provider errors still produce :adapter_error as before.

Why not a 0.6.x deprecation first?

Closed the previous PR #12 (which added a deprecation warning in 0.6.5) because this gem has no real external user base. A deprecation → grace period → breaking pattern is enterprise theater when nobody is between releases to see the warning. Ship the change, document migration clearly.

Migration

Restore pre-0.7 behavior (if you were relying on :adapter_error retry):

retry_policy do
  attempts 3
  retry_on :validation_failed, :parse_error, :adapter_error
end

Preferred pattern — pair with a model fallback chain:

retry_policy do
  escalate "gpt-4.1-nano", "gpt-4.1-mini"
  retry_on :validation_failed, :parse_error, :adapter_error
end

Test plan

• bundle exec rspec — 1336 examples, 0 failures, 8 pending (all pending are API-key-gated live LLM tests)
• bundle exec rubocop lib/ruby_llm/contract/step/retry_policy.rb lib/ruby_llm/contract/step/adapter_caller.rb — no offenses
• Updated existing specs: :adapter_error retry tests now use explicit retry_on :adapter_error opt-in; adapter failure fixtures raise RubyLLM::Error instead of StandardError; adversarial test inverted (:adapter_error is NOT retryable by default + new test for explicit opt-in).
• Version bump 0.6.4 → 0.7.0; Gemfile.lock updated.

[Copilot]

Pull request overview

This PR introduces the 0.7.0 breaking changes to retry behavior and adapter error handling to reduce redundant retries and avoid masking programmer/configuration errors.

Changes:

• Remove :adapter_error from RetryPolicy::DEFAULT_RETRY_ON (now defaults to [:validation_failed, :parse_error]).
• Narrow AdapterCaller rescue from StandardError to ::RubyLLM::Error, allowing non-provider errors to propagate.
• Update specs, changelog, and version/lockfile for the 0.7.0 release and new opt-in behavior.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
spec/ruby_llm/contract/step/runner_spec.rb	Updates adapter failure fixture to raise RubyLLM::Error.
spec/ruby_llm/contract/step/retry_policy_spec.rb	Updates default retryable statuses expectation to exclude :adapter_error.
spec/ruby_llm/contract/step/retry_integration_spec.rb	Makes :adapter_error retry behavior explicit via retry_on :adapter_error and updates fixtures.
spec/ruby_llm/contract/edge_cases_spec.rb	Updates adapter failure fixture to raise RubyLLM::Error.
spec/ruby_llm/contract/adversarial_round10_spec.rb	Inverts default retryability expectation for :adapter_error and adds explicit opt-in test.
spec/integration/step_end_to_end_spec.rb	Updates adapter failure fixture to raise RubyLLM::Error.
lib/ruby_llm/contract/version.rb	Bumps gem version to 0.7.0.
lib/ruby_llm/contract/step/retry_policy.rb	Changes retry defaults and documents the breaking rationale.
lib/ruby_llm/contract/step/adapter_caller.rb	Narrows rescue to ::RubyLLM::Error and preserves :adapter_error mapping for provider errors.
Gemfile.lock	Updates lockfile entry for ruby_llm-contract to 0.7.0.
CHANGELOG.md	Adds 0.7.0 release notes and migration guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The change to only rescue ::RubyLLM::Error is a breaking behavioral change, but there doesn’t appear to be a spec that asserts a non-RubyLLM::Error raised by an adapter (e.g., ArgumentError/NoMethodError) now propagates instead of being coerced into :adapter_error. Adding an explicit regression spec for this new contract would help prevent accidental broadening of the rescue in the future.

[justi]

Codex review findings addressed in the amended commit.

P1 (transport errors leaking) — fixed. AdapterCaller#rescue now catches ::RubyLLM::Error and ::Faraday::Error. Faraday re-raises Faraday::TimeoutError / Faraday::ConnectionFailed after its retry middleware exhausts, and these aren't in the RubyLLM::Error hierarchy — the narrower rescue would have leaked them. Added 3 regression specs in retry_integration_spec.rb under "transport error handling (Codex review regression)":

• Faraday::TimeoutError → :adapter_error (Codex verified this leaked without the fix)
• Faraday::ConnectionFailed → :adapter_error
• NoMethodError (programmer bug) → propagates as NoMethodError

P2 (ArgumentError still coerced to :input_error) — acknowledged as known limitation. Step::Base#run_once rescues ArgumentError for input-type validation (dry-types raises this path). Disambiguating adapter-ArgumentError vs input-validation-ArgumentError requires refactoring run_once to scope the rescue narrowly around the type-check boundary, not around the whole Runner. That's a distinct change in scope; called out in the CHANGELOG as known limitation and left as a follow-up.

Full suite: 1339 examples, 0 failures, 8 pending.

[justi]

@copilot-pull-request-reviewer Review was on the pre-amend commit. The current HEAD (f9eae16) already has the regression spec you requested: spec/ruby_llm/contract/step/retry_integration_spec.rb:508 — it "propagates NoMethodError from adapter (programmer bug, not transport)" — asserts that non-RubyLLM::Error / non-Faraday::Error adapter exceptions propagate via raise_error(NoMethodError) instead of being coerced into :adapter_error. Two sibling specs also cover the Faraday::TimeoutError and Faraday::ConnectionFailed paths that Codex review found were leaking; all three live under the "transport error handling (Codex review regression)" describe block.