lex-llm-vllm 0.4.6 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d68ddb8f9c969ef5991b7437e6d0d9cea05f2e4dfe9f39fbb9696ec513988b4f
-  data.tar.gz: 9fa21d69ed1c20795872db8648140c4d89b8155487a6def3f0fe7f121bf39e1e
+  metadata.gz: 30dbfef3f26068d2f15e577896bc3e2964d5ef9fbb319282677eb89e2e084cdb
+  data.tar.gz: 8ff7f24fa3596e787f07a5877344a954af4e1e3c607d5483db0b7f3adc4a8dbc
 SHA512:
-  metadata.gz: 5a372fff3346ff953fe4265073c19cefe72064a2592adb2d8313f2a61241d657424afd1eeb973284d3c15269500c04bcf47b16402317e9c240aebe2c213d62ad
-  data.tar.gz: f2ea87b7809e88965c53c19f412c3c37eb1036a3ffab1cf20bedf60c9c672c6cb918aee3aaf96ee1df513da7815fe287c84ccc8b09808ce6ef96ab5704cc5664
+  metadata.gz: bb1987843cd6920607c409b0b29b1f7730ed9cf2fcd914abc1a84cd48c3f577c54a7bd442e75747c0d085de1f8299112559e0960b02f280e7db429af29f10976
+  data.tar.gz: d776249cffeaa2fd169ffa899cb005ce2ac84e22ab1725c8ed8fba183a4a677489bffb3006c31eaad42827a65cf9c1d1cd5cacfa9840d9b0c305687feff39389

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.4.8] - 2026-08-25
+
+### Changed
+- **Canonical Thinking::Config transposition.** The vLLM translator now renders the full expanded thinking config to wire:
+  - `enabled: false` renders `enable_thinking: false` (forces a default-ON model off).
+  - `enabled: true` renders `enable_thinking: true` + `thinking_budget` derived from `Thinking::Config#resolved_budget` (effort ladder: none|low|medium|high|xhigh|max → budget).
+  - The `params.max_thinking_tokens` dual-home is removed — `resolved_budget` is the single derivation path.
+- **Usage normalization at the provider boundary (O03a).** `canonical_usage` translates the OpenAI Chat wire usage dialect (`prompt_tokens`/`completion_tokens` + nested `*_details`) into canonical keys before `Usage.from_hash`, preventing wire spellings from folding into metadata with nil token counts.
+
+### Removed
+- `log_unsupported_params` (referenced deleted `params.max_thinking_tokens`).
+
+## [0.4.7] - 2026-08-20
+
+### Changed
+- **lex-llm 0.8.0 conformance (SSOT v4 contract cut).** Migrate the provider, callable, and translator to the Canonical-only boundary:
+  - The provider render/parse boundaries render FROM canonical values and parse TO canonical types (`Canonical::Response` for sync, `Canonical::Chunk` for streaming); the `to_legacy_message`/`to_legacy_chunk` bridges and the legacy `Llm::Message`/`Llm::Chunk`/`Llm::ToolCall` reconstruction are deleted.
+  - `temperature` is no longer a render kwarg (05 O4): the funnel's `Canonical::Params` (or Hash) flows into the vLLM dialect translator, and the edge `schema` folds into `params.response_format` at the render boundary.
+  - The callable's `chat`/`stream_chat` adopt the 0.8.0 callable contract (positional canonical messages; temperature travels inside `params`).
+  - Streaming tool-call deltas emit the documented fragment shape (`{ id:, name:, arguments: <String fragment>, index: }`) instead of a full `Canonical::ToolCall` with a String `arguments` member (O03a: `arguments` is Hash-only, and the accumulator reads the fragment by symbol keys); the sync tool-call path parses through the ONE shared strict arguments parser (`Responses::ToolArguments.parse!`, 10 U2) — the rescue-to-`{}` tolerance is gone (04 L7: invalid JSON is a contract error).
+  - The offerings read path (`discover_offerings`) is served from the SSOT Registry snapshot by the base read path (07 C5); the legacy `offering_from_model` → `Routing::ModelOffering` production path and its filter cache are deleted — the per-gem writer (`Helpers::OfferingBuilder` + `Runners::DiscoveryRefresh`) is the sole publication path.
+- Enforce the canonical dispatch boundary end to end: the fleet callable's chat, stream_chat, and count_tokens operations reject plain-Hash messages with a loud ArgumentError instead of silently re-canonicalizing them. The lenient hash re-canonicalization masked the 2026-08-19 hash-bypass defect for 25 failed openai dispatches; it is removed.
+- Prompt-cache `cache_control` rides as a first-class `Canonical::Message` member; the vLLM OpenAI-compatible wire render drops it, so the wire format is unchanged.
+- Raise the `lex-llm` dependency floor to 0.8.0.
+- The local-tree `lex-llm` path dependency in the test group resolves against the 0.8.0 contract cut during development.
+
+### Removed
+- `LegacyCoordinatorAdapter` compatibility wiring from the discovery runner (`Inventory::ScopedRefresher` is deleted in lex-llm 0.8.0); the `Inventory::Publisher` is constructed without a compatibility adapter.
+- The render-seam `build_canonical_messages` re-check — central enforcement (`Provider#enforce_canonical_messages!` in the `complete` funnel) is the one check point (08 F2).
+
+### Added
+- Conformance kit B1–B4 boundary groups run against the production `VllmCallable`: central canonical enforcement (08 F2), canonical outputs asserted by type (05 O5, 08 R2), operation preservation (PR #189 defect class), and no model re-derivation (PR #45 law).
+- Cover the canonical boundary in the dispatch-boundary conformance block: the canonical `cache_control` member survives on the message, the wire never leaks it, and plain-Hash input raises at the callable boundary and the `complete` funnel.
+
 ## [0.4.6] - 2026-08-19
 
 ### Changed

data/Gemfile

@@ -2,10 +2,15 @@
 
 source 'https://rubygems.org'
 
-gem 'lex-llm'
-
 gemspec
 
+# Local-tree resolution: use the adjacent lex-llm checkout when present so the
+# 0.8.0 conformance work resolves against the contract cut during development.
+group :test do
+  lex_llm_path = File.expand_path('../lex-llm', __dir__)
+  gem 'lex-llm', path: lex_llm_path if Dir.exist?(lex_llm_path)
+end
+
 group :development do
   gem 'bundler', '>= 2.0'
   gem 'rake', '>= 13.0'

data/RULES.md

@@ -0,0 +1,97 @@
+RULES.md — Legion LLM Architecture Law
+These rules apply to every task, file, repository, agent, model, session, test, refactor, migration, incident, and release.
+The requested task defines what may change. These rules define how the system ALWAYS works.
+Every rule remains active 100% of the time. If requested work conflicts with these rules, stop and surface the conflict before changing code.
+These are architecture laws. Scope, compatibility, urgency, convenience, tests, existing behavior, and model judgment do not change them.
+1. Canonical is the only internal language.
+Every client translates client wire -> Canonical before shared execution.
+Shared execution carries Canonical through context, tools, routing, direct dispatch, fleet dispatch, and response handling.
+Every provider translates Canonical -> provider wire at the provider boundary, then provider wire -> Canonical before returning to shared execution.
+Every internal boundary validates the Canonical type it is defined to receive and raises immediately when that contract is violated.
+Client Wire -> Client Translator -> Canonical -> Shared Execution -> Canonical -> Provider Translator -> Provider Wire.
+2. Serialization preserves Canonical.
+Transport may serialize Canonical state. The receiving transport boundary ALWAYS rehydrates the exact Canonical type before execution continues.
+Fleet follows Canonical -> serialize -> wire -> deserialize -> rehydrate Canonical -> Canonical.
+Serialization changes encoding only. Ownership, identity, model, operation, capability, selection, and meaning remain exactly the same.
+After rehydration, shared execution continues only with Canonical objects.
+3. Every authoritative fact has exactly one owner.
+The owner creates the fact once. Every downstream layer carries, projects, serializes, rehydrates, verifies, or executes that exact fact.
+A downstream layer receiving missing or contradictory authoritative state raises and returns the defect to the owning layer.
+Authority ALWAYS moves forward by preservation.
+Authority is created once and is never recreated downstream.
+4. Requirements describe the request. Inventory describes reality. Router chooses. Dispatch executes.
+Canonical request construction owns request semantics. RequestRequirements expresses operation, capabilities, modality, context, output, tools, and explicit pins.
+Providers publish exact executable facts into Inventory. Inventory owns canonical instance, offering, lane, capability, context, quota, health, and published weight state.
+Router.next_lane consumes Requirements plus one immutable Inventory snapshot and produces one authoritative Selection.
+Dispatch executes that Selection exactly. Once Selection exists, routing is finished.
+5. Inventory facts are immutable executable facts.
+Providers publish exact instances and complete offering snapshots through the Inventory publication contract.
+Identity, capability evidence, context evidence, quota domains, availability, and write-time weights are consumed from published Inventory state.
+A changed fact becomes authoritative only through the owning publication or reconciliation path and a new Inventory snapshot.
+Routing reads Inventory. Dispatch verifies and executes Inventory-backed Selection.
+6. Identity, capabilities, weights, and context policy retain exact ownership.
+Inventory::Identity owns instance, offering, and lane identity; canonical instance identity is provider family plus the operator/configured instance name; physical endpoint data remains secondary.
+Providers publish capability evidence. Requirements state required capabilities. Candidate evaluation compares the two and determines capability eligibility.
+The weight owner computes lane weight at publication time; Inventory stores it; ranking consumes that stored weight; a stored zero disables the lane.
+Preferred-context binning orders eligible candidates into preference bands and preserves eligibility. Capability, health, binning, and weight ALWAYS retain distinct meanings.
+7. Routing chooses exactly once.
+Router.next_lane is the sole routing authority.
+Candidate evaluation determines eligibility from Requirements and Inventory. Ranking orders eligible candidates from published routing facts.
+Selection freezes the exact provider, instance, offering, lane, model, operation, and routing identity required for execution.
+Every downstream component consumes the Selection it receives.
+Selection is preserved, not reconstructed.
+8. Exact execution stays exact through every boundary.
+Direct dispatch executes the exact Selection-derived binding it receives.
+Fleet dispatch serializes and signs that exact binding; fleet validation verifies it; fleet rehydration restores it; worker resolution verifies it against authoritative Inventory.
+The selected provider, instance, offering, lane, model, and operation remain identical through projection, signing, transport, validation, rehydration, resolution, and callable invocation.
+A mismatch raises before provider execution.
+An exact execution request ALWAYS remains exact execution.
+9. Health and errors preserve one authoritative meaning.
+Inventory owns exact-instance availability. An authoritative instance-unavailable result removes that exact instance; readiness probing owns recovery; successful readiness republish re-admits it.
+Overload, timeout, rate limit, model-not-ready, and transient provider failures remain request-local according to ProviderOutcome semantics.
+The first layer that can authoritatively classify an error performs that classification once. Every downstream layer preserves it.
+Programming errors remain programming errors. Contract violations remain contract violations. Routing exhaustion remains the defined typed Rejection.
+10. Compatibility exists only at explicit edges.
+Supported legacy clients and protocols are translated into the current Canonical and SSOT architecture at explicit compatibility boundaries.
+Shared execution remains Canonical. Routing remains SSOT-driven. Exact execution remains exact.
+Compatibility code adapts an external contract to the current internal architecture.
+The current internal architecture ALWAYS has one representation, one routing authority, one identity system, and one execution truth.
+11. Fix every defect at its owner.
+Trace the incorrect value to the layer that owns it, then fix that owner.
+Fix client wire in the client translator; Canonical shape in Canonical construction; Requirements in Requirements construction; provider facts in publication; identity in Inventory identity; weights in publication/reconciliation.
+Fix eligibility in candidate evaluation; ordering in ranking; choice in Router.next_lane; execution preservation in dispatch; provider wire in the provider translator.
+The layer where a defect becomes visible is evidence. The owning layer is where the correction belongs.
+12. A discovered issue remains in its owning domain.
+Complete the requested task inside its stated scope.
+When investigation exposes a separate defect owned by another architectural domain, record and surface it as separate work unless the requested task is explicitly expanded.
+Routing work consumes existing Canonical Requirements and Inventory facts. Canonical work changes Canonical contracts. Provider work changes publication or translation. Transport work changes transport.
+Nearby code never changes ownership. “While we are here” never changes architecture.
+13. N x N ALWAYS converges through Canonical.
+Equivalent client semantics produce equivalent Canonical state before shared execution. Every provider consumes the same Canonical semantics for the same request.
+When two paths disagree, capture the state at every involved boundary and locate the FIRST point where Canonical meaning diverges.
+Fix that first divergent boundary, then run the exact failing path again.
+Client behavior is proven at client-wire <-> Canonical. Provider behavior is proven at Canonical <-> provider-wire. Shared execution is proven with Canonical throughout.
+14. Debug from captured authoritative state.
+Capture the actual input at the failing boundary before reasoning from symptoms.
+For translation or transport defects, capture Canonical immediately before and after every involved boundary.
+For routing or dispatch defects, capture Requirements, relevant Inventory facts, Selection, execution binding, and ProviderOutcome.
+Compare each captured value to the contract owned by that layer. Find the first divergence. Fix its owner. Re-run the exact path.
+Then inspect sibling implementations for the same defect class.
+15. Tests prove the real boundary and the invariant.
+A boundary test exercises the real boundary it claims to protect.
+Fleet tests exercise real serialization, deserialization, Canonical rehydration, signing, validation, exact resolution, and callable dispatch.
+Provider tests exercise the real callable boundary and provider translator. Routing tests exercise real Requirements, Inventory records, candidate evaluation, ranking, and Selection.
+Regression tests prove the violated invariant, not only the observed symptom.
+A green suite is release evidence only when the tested path traverses the real architecture.
+16. Shared contracts are consumed directly.
+Shared Canonical types own execution representation. Shared Inventory types own inventory state. Shared Routing types own routing state.
+Shared taxonomy owns canonical mappings. Shared ProviderOutcome owns provider-neutral outcomes. Shared fleet protocol owns exact execution claims.
+Every repository consumes these shared owners directly.
+A defect in one shared boundary triggers an audit of every sibling implementation of that boundary. Fix the shared owner centrally whenever the defect belongs to a shared contract.
+17. Architecture is the release gate.
+Every change preserves every rule in this file.
+Tests, compatibility, historical behavior, migration phase, patch urgency, nearby code, task wording, and model judgment are evaluated UNDER these rules.
+A contradiction between existing behavior and these rules is surfaced as an architecture conflict and resolved at the owning boundary before release.
+Limited scope means do less. Limited scope NEVER means fewer rules apply.
+These rules apply 100% of the time.
+These are the law.

data/lex-llm-vllm.gemspec

@@ -27,7 +27,10 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.4.2'
   spec.add_dependency 'legion-transport', '>= 1.4.14'
-  # 0.7.6 carries the write-time weight schema/reconciler and the immutable
-  # OfferingDraft/OfferingRecord/LaneRecord weight pair used by this writer.
-  spec.add_dependency 'lex-llm', '>= 0.7.6'
+  # 0.8.0 is the canonical contract cut: Canonical-only funnel (central
+  # enforcement, temperature in Params, positional-messages callable
+  # contract), the legacy Llm::Message/Chunk/ToolCall/ModelOffering/
+  # ScopedRefresher surface is deleted, and the per-gem writer publishes
+  # OfferingDrafts through the SSOT Registry.
+  spec.add_dependency 'lex-llm', '>= 0.8.0'
 end

data/lib/legion/extensions/llm/vllm/actors/discovery.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/discovery/actor'
+
+# The base discovery actor only exists inside the daemon (it inherits the
+# LegionIO time-based Every actor). In a standalone load, define nothing.
+return unless defined?(Legion::Extensions::Llm::Discovery::Actor)
+
+module Legion
+  module Extensions
+    module Llm
+      module Vllm
+        module Actor
+          # vLLM discovery actor: an EMPTY subclass of the shared base. The timer,
+          # the dispatch, and the runner-resolution convention are inherited —
+          # this class redefines nothing. The vLLM-specific work lives in
+          # Vllm::Runners::Discovery, resolved by the base from this namespace.
+          class Discovery < Legion::Extensions::Llm::Discovery::Actor; end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/vllm/helpers/callable.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/routing/provider_outcome'
+require 'legion/extensions/llm/vllm/provider'
+
+module Legion
+  module Extensions
+    module Llm
+      module Vllm
+        module Helpers
+          # Callable wrapper for a vLLM provider instance. Implements the
+          # `disconnect` and `normalize_dispatch_error(error:)` contracts required
+          # by Inventory::CallableHandle and Routing::ProviderOutcome, plus the
+          # fleet dispatch operations the coordinator invokes (chat, stream_chat,
+          # embed, count_tokens). Each dispatch delegates to a per-instance
+          # Vllm::Provider built lazily from the instance config; provider and
+          # Faraday errors are NOT rescued here so the coordinator's
+          # normalize_dispatch_error can classify them.
+          class Callable
+            # Keys the base Provider exposes as named kwargs for the completion
+            # operations. Anything else the fleet passes is folded into the
+            # payload `params` hash (temperature is a Canonical::Params member,
+            # never a named kwarg — 05 O4).
+            COMPLETION_NAMED_KEYS = %i[tools schema thinking tool_prefs headers].freeze
+            EMBED_NAMED_KEYS = %i[dimensions headers].freeze
+
+            def initialize(instance_cfg:, logger:)
+              @instance_cfg = instance_cfg
+              @logger = logger
+              @disconnected = false
+              @inference_calls = 0
+            end
+
+            def call_count
+              @inference_calls
+            end
+
+            def disconnected?
+              @disconnected
+            end
+
+            def disconnect
+              @disconnected = true
+              @provider&.disconnect
+              @logger.debug { '[vllm][callable] disconnected' }
+            end
+
+            # ── Fleet dispatch operations ──────────────────────────────────────
+
+            # 0.8.0 callable contract: chat/stream_chat take the canonical
+            # messages positionally (the fleet dispatch and the conformance kit
+            # both call `callable.chat(messages, model:, ...)`); count_tokens
+            # and embed keep their keyword forms.
+            def chat(messages, model:, **rest)
+              record_inference
+              # Canonical boundary (N x N law): pipeline dispatch delivers
+              # Canonical::Message objects only. Hash/legacy shapes are the
+              # bypass class — reject loudly, never coerce.
+              provider.enforce_canonical_messages!(messages)
+              named, params = split_fleet_kwargs(rest, COMPLETION_NAMED_KEYS)
+              provider.chat(messages, model: model, params: canonical_params(params), **named)
+            end
+
+            def stream_chat(messages, model:, **rest, &)
+              record_inference
+              provider.enforce_canonical_messages!(messages)
+              named, params = split_fleet_kwargs(rest, COMPLETION_NAMED_KEYS)
+              provider.stream_chat(messages, model: model, params: canonical_params(params), **named, &)
+            end
+
+            def embed(text:, model:, **rest)
+              record_inference
+              named, params = split_fleet_kwargs(rest, EMBED_NAMED_KEYS)
+              provider.embed(text: text, model: model, params: params, **named)
+            end
+
+            def count_tokens(messages:, model:, **rest)
+              record_inference
+              provider.enforce_canonical_messages!(messages)
+              _named, params = split_fleet_kwargs(rest, [])
+              provider.count_tokens(messages: messages, model: model, params: params)
+            end
+
+            # V5: the reason is the bounded exception CLASS name (the base
+            # contract) — never the message, which embeds endpoint URLs and
+            # provider error bodies that must not reach shared state. The
+            # kind override stays: vLLM's explicit offline body phrases are
+            # stronger evidence than a raw status (the base law that raw 503
+            # alone never manufactures unavailability is preserved).
+            def normalize_dispatch_error(error:)
+              kind = classify_dispatch_error(error: error)
+              reason = error.class.name
+              reason = 'UnknownError' if reason.nil? || reason.empty?
+              Legion::Extensions::Llm::Routing::ProviderOutcome.new(kind: kind, reason: reason)
+            end
+
+            private
+
+            def record_inference
+              @inference_calls += 1
+            end
+
+            def provider
+              @provider ||= Legion::Extensions::Llm::Vllm::Provider.new(@instance_cfg)
+            end
+
+            # The 0.8.0 completion funnel receives canonical values only
+            # (08 F3): the folded wire params become a Canonical::Params at
+            # the dispatch boundary — temperature is a params member (05 O4),
+            # never a kwarg.
+            def canonical_params(params)
+              Legion::Extensions::Llm::Canonical::Params.from_hash(params)
+            end
+
+            # Split the fleet's **rest into the base Provider's named kwargs and a
+            # payload params hash (any passed :params merged with unknown keys).
+            def split_fleet_kwargs(rest, named_keys)
+              named = rest.slice(*named_keys)
+              extra = rest.reject { |key, _| named.key?(key) }
+              params = (extra.delete(:params) || {}).to_h.merge(extra)
+              [named, params]
+            end
+
+            # D17: in production the base Connection's ErrorMiddleware raises
+            # Legion::Extensions::Llm::*Error (NOT raw Faraday classes), so this
+            # maps the full Llm error set (mirroring base Provider#
+            # normalize_dispatch_error) and layers the vLLM offline-body detection
+            # on top. Raw Faraday classes are also handled for the direct-HTTP
+            # paths that bypass the middleware.
+            def classify_dispatch_error(error:)
+              case error
+              when Legion::Extensions::Llm::OverloadedError then :overloaded
+              when Legion::Extensions::Llm::RateLimitError then :rate_limited
+              when Legion::Extensions::Llm::UnauthorizedError then :authentication
+              when Legion::Extensions::Llm::PaymentRequiredError then :billing
+              when Legion::Extensions::Llm::ForbiddenError then :authorization
+              when Legion::Extensions::Llm::ContextLengthExceededError then :context_rejected
+              when Legion::Extensions::Llm::BadRequestError then :invalid_request
+              when Legion::Extensions::Llm::ModelNotFoundError then :model_missing
+              when Legion::Extensions::Llm::ModelNotAllowedError then :policy
+              when Legion::Extensions::Llm::ServiceUnavailableError
+                if explicit_vllm_offline?(status: dispatch_error_status(error:),
+                                          body: dispatch_error_body(error:))
+                  :instance_unavailable
+                else
+                  :provider_error
+                end
+              when Legion::Extensions::Llm::ServerError then :provider_error
+              when Faraday::TimeoutError, Timeout::Error then :timeout
+              when Faraday::ConnectionFailed, Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError
+                :connection_failure
+              when Faraday::ClientError then classify_client_error(error:)
+              when Faraday::ServerError then classify_server_error(error:)
+              else :provider_error
+              end
+            end
+
+            def classify_client_error(error:)
+              case dispatch_error_status(error:)
+              when 401 then :authentication
+              when 403 then :authorization
+              when 404 then :model_missing
+              when 429 then :rate_limited
+              else          :invalid_request
+              end
+            end
+
+            def classify_server_error(error:)
+              status = dispatch_error_status(error:)
+              return :instance_unavailable if explicit_vllm_offline?(status: status, body: dispatch_error_body(error:))
+
+              case status
+              when 503, 529 then :overloaded
+              else               :provider_error
+              end
+            end
+
+            # Read the HTTP status off a dispatch error whether its response is a
+            # plain Hash, a Faraday::Response, or a Faraday::Env. Real Faraday
+            # errors carry a Faraday::Env (a Struct, NOT a Hash), so a legacy
+            # `error.response.is_a?(Hash)` gate would never fire in production.
+            def dispatch_error_status(error:)
+              return error.response_status if error.respond_to?(:response_status) && !error.response_status.nil?
+
+              response = error.response if error.respond_to?(:response)
+              return response.status if response.respond_to?(:status) && !response.status.nil?
+
+              response[:status] if response.respond_to?(:[]) && !response[:status].nil?
+            end
+
+            def dispatch_error_body(error:)
+              return error.response_body.to_s if error.respond_to?(:response_body) && !error.response_body.nil?
+
+              response = error.response if error.respond_to?(:response)
+              return response.body.to_s if response.respond_to?(:body) && !response.body.nil?
+
+              response[:body].to_s if response.respond_to?(:[]) && !response[:body].nil?
+            end
+
+            # An explicit flat vLLM service-offline body (never just HTTP 503
+            # alone). connection_failure, timeout, overload, 429, and generic 5xx
+            # are request-local per §8 and must not map to instance_unavailable.
+            def explicit_vllm_offline?(status:, body:)
+              status == 503 && (
+                body.to_s.downcase.include?('instance not available') ||
+                body.to_s.downcase.include?('server is going offline') ||
+                body.to_s.downcase.include?('service unavailable, server offline')
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end