lex-llm-openai 0.6.3 → 0.6.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84567e208562add7567e8de290c9d69ce3a7ae7e10cfab7e7e6ddf92173d2b7d
-  data.tar.gz: 912a0379793e6e7dc10353aaf198ddc2c08b50310eb1642b8e2f7e5f1f244010
+  metadata.gz: ac62eb3f6a56c5f0b41acde2dd6a2e5e4d6f2bfe7453752514d9c8c3749dde2b
+  data.tar.gz: dd0d4d972f11c95d278256cdd0a739dea0de4f411f182efc657c2f4123d2c727
 SHA512:
-  metadata.gz: a92b8cc928c93cf271ab575f15a9c582ddb4a53ceab09f8d0817a9b4268abc4dddcb997a11e926490c739798a9f25b763ea7cdbe3e348b328570f6ee3714b1fb
-  data.tar.gz: f8686fa71f7b9a23b7ee2f0a26bd74b8ea44afbefc33f6c47f0ed3836c34fe3e75acce1cd49bc98407a9ecf41e4937642f84b3fe0ce50f5d24c66b1f0da29884
+  metadata.gz: 326a853929579295e753e33689aec41d7b202b811d972ebbc463e312d8e82cfcdaaa60b8b6bfcadfc9262cbd1b5c0b3871c0c9e79159c507217302ba37ac235b
+  data.tar.gz: b14ec226c2d960d06cf9af29d79fafe655102627d516d342d6b31fe64a8c8e4939e059a8eb1d12bab56e4f7d81dc1361d4f23bd1e3138421c5aebcbc827e80be

data/.rubocop.yml

@@ -14,8 +14,11 @@ Metrics/BlockLength:
     - spec/**/*
 Metrics/ClassLength:
   Max: 350
+# Aligned with the sibling lex-llm-* providers (vllm/gemini/mlx): the rubocop
+# default ModuleLength is too strict for a discovery runner carrying the full
+# evidence-building surface. Length is still bounded (Max 350).
 Metrics/ModuleLength:
-  Max: 110
+  Max: 350
 Metrics/MethodLength:
   Enabled: false
 RSpec/ExampleLength:

data/CHANGELOG.md

@@ -1,9 +1,44 @@
 # Changelog
 
+## [0.6.6] - 2026-08-25
+
+### Fixed
+- **Thinking contract aligned to lex-llm 0.8.x** — removed dead `params.max_thinking_tokens` reference in `apply_format_params` (NoMethodError on every request reaching this path since Params dropped that member). `apply_thinking` now gates on `thinking.enabled?` and uses `thinking.resolved_effort` so a budget-only client still yields `reasoning_effort` on the wire (never silently dropped). The `respond_to?(:effort)` Hash shim is removed — `thinking` is always a `Canonical::Thinking::Config` or nil.
+
 ## [Unreleased]
 
+### Changed
+- **lex-llm 0.8.0 conformance** — the gem now runs against the 0.8.0 contract cut; lex-llm floor bumped to `>= 0.8.0`. Version remains 0.6.5 per the 0.8.0-conformant release law.
+- **Legacy offering production ripped** — the provider's legacy `discover_offerings` override and its `Routing::ModelOffering` production path (offering attrs, capability-policy resolution, instance-id derivation, filter helpers) are deleted; `discover_offerings` is now the base 0.8.0 read path serving activated offerings from the `Inventory::Registry` snapshot (07 C5). The `DiscoveryRefresh` writer (`OfferingDraft` + `WeightReconciler` + `Publisher`) remains the sole publication path.
+- **Legacy coordinator wiring ripped** — the `ScopedRefresher::LegacyCoordinatorAdapter` bridge is removed from the discovery actor (the file is gone from lex-llm 0.8.0); the `Publisher` is constructed without a compatibility adapter.
+- **Callable aligned to the 0.8.0 fleet dispatch shape** — `chat`/`stream_chat` take positional canonical `messages` (the 0.8.0 funnel signature) and hand the Selection-derived model to the wire UNCHANGED (B4): the `Model::Info` wrap for chat/stream_chat is deleted because the 0.8.0 renderer consumes `model:` verbatim (a wrapped value would serialize a Data object into the request payload). `moderate` now takes `input:` as a keyword, matching the base `Provider#moderate(input:, model:)` contract (the previous positional call raised `ArgumentError` against 0.8.0). Fleet wire params are folded into `Canonical::Params` at the dispatch boundary (`Canonical::Params.from_hash`; `temperature` is a params member, 05 O4 — it is no longer a named completion kwarg on any provider path); base named kwargs (`tools`/`schema`/`thinking`/`tool_prefs`/`headers`, and `dimensions`/`headers` for embed) pass through as-is. No tools/thinking wire rehydration — logged pre-existing gap, out of this wave.
+- **Renderer/parser on the 0.8.0 canonical contract** — `render_payload` renders from canonical values (`params:` replaces the deleted `temperature:` kwarg); the o-series/gpt-5 temperature clamp and `-search` suppression (previously reachable through the 0.7.x funnel hook) are preserved at the render path as `normalize_openai_temperature`. The local render-seam message check is deleted — canonical input is enforced centrally in the base `complete` funnel (08 F2). `Translator#parse_usage` translates the OpenAI wire spellings (`prompt_tokens`/`completion_tokens` and the Responses API `input_tokens`/`output_tokens`) to canonical keys at the edge (O03a: canonical types accept canonical keys only).
+- **RULES.md installed** at the repo root (byte-for-byte, the 0.8.0 architecture law mirror).
+
+### Removed
+- `Provider#enforce_render_messages!` and the legacy `Llm::Message` acceptance at the render seam (the type is deleted in 0.8.0; the Chat-facade shape is gone).
+- The capability-policy read-path spec (it pinned the deleted `Routing::ModelOffering` surface; the writer-path capability evidence is pinned by the discovery and conformance specs).
+
+## [0.6.5] - 2026-08-19
+
+### Changed
+- **Canonical dispatch boundary enforced** — `OpenaiCallable#chat`, `#stream_chat`, and `#count_tokens` now call `Provider#enforce_canonical_messages!` before delegating, and the provider's render seam accepts only `Canonical::Message` (pipeline dispatch) or provider-native `Legion::Extensions::Llm::Message` (Chat facade); anything else raises a loud `ArgumentError` at the boundary instead of failing opaquely downstream and being misclassified as a provider error. The 2026-08-19 incident: SSOT v3 local dispatch passed executor Hash messages straight to the provider callable, bypassing the canonical contract (25/25 failed openai dispatches). N x N law: client translator = client <-> Canonical, executor = Canonical throughout, provider translator = Canonical <-> provider wire — anything half-translated between Canonical and a legacy shape is the defect class this boundary kills.
+- **lex-llm floor bumped to >= 0.7.7** — for `Provider#enforce_canonical_messages!` and the canonical-only `count_tokens`.
+- **Local-tree lex-llm path dependency added to the test group** so the adjacent checkout resolves against unreleased 0.7.7 during development.
+
+### Added
+- Dispatch-boundary regression guards: plain-Hash input raises `ArgumentError` at both the fleet callable and the provider render seam; provider-native `Message` input renders to the unchanged OpenAI wire. Client request formats and the provider wire format are unchanged.
+
+## [0.6.4] - 2026-08-19
+
 ### Fixed
+- **Write-time lane weights** — every discovered offering now carries the validated four-axis `weight_inputs` and `base_weight` pair from live settings. The existing periodic actor cadence atomically compares, publishes, sequences, and caches catalog or weight-only changes; unchanged passes stay no-op, initializing instances cache without replacing, and removals cannot race into late activation.
+- **Dormant weight visibility** — ordinary discovery passes emit one info log when a configured provider, instance, model, or offering weight has no published lane; the state clears when the lane appears and logs once again if it later disappears.
+- **D14 callable wire conformance** — an actual `OpenaiCallable#chat` request with a folded leading system message is captured at the provider connection and verified as OpenAI's native leading `role: system` message.
+- **Malformed discovery failures fail loud** — programming/configuration errors from draft construction are no longer swallowed as an empty catalog; only Faraday transport failures and JSON parse failures take the existing empty-discovery recovery path.
+- **lex-llm floor bumped to >= 0.7.6** — requires the shared `WeightSchema`, atomic `WeightReconciler`, weighted offering records, and operation-to-lane taxonomy used by this writer. The `legion-settings >= 1.4.2` floor and lifecycle remain unchanged.
 - **Credential-less configured instances are discovered normally** — removed the synthetic-default suppression and its one-time warning cache. A configured instance, including one named `default`, now follows the ordinary discovery and readiness path without a skip warning.
+- **Complete offering equivalence** — ordinary discovery now compares the complete `OfferingDraft` contract as an order-insensitive, duplicate-sensitive multiset, ignoring only evidence `observed_at` timestamps. Provider-native identity, publication source, tokenizer evidence, and all future draft fields trigger exactly one replacement when they change, while catalog reordering remains a no-op.
 
 ## [0.6.2] - 2026-08-17
 

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
+# canonical-boundary work resolves against the unreleased 0.7.7.
+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-openai.gemspec

@@ -27,5 +27,5 @@ 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'
-  spec.add_dependency 'lex-llm', '>= 0.7.1'
+  spec.add_dependency 'lex-llm', '>= 0.8.0'
 end

data/lib/legion/extensions/llm/openai/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 Openai
+        module Actor
+          # OpenAI discovery actor: an EMPTY subclass of the shared base. The
+          # timer, dispatch, and runner-resolution convention are inherited —
+          # this class redefines nothing. The OpenAI-specific work lives in
+          # Openai::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/openai/helpers/callable.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'legion/extensions/llm/routing/provider_outcome'
+
+module Legion
+  module Extensions
+    module Llm
+      module Openai
+        module Helpers
+          # Callable wrapper for an OpenAI provider instance. Implements the
+          # fleet dispatch operations by delegating to the per-instance
+          # Openai::Provider (errors propagate so normalize_dispatch_error can
+          # classify them), plus the `disconnect` and `normalize_dispatch_error
+          # (error:)` contracts required by Inventory::CallableHandle and
+          # Routing::ProviderOutcome.
+          #
+          # Defined in its own file so the actor's runtime guard (the Every base
+          # is absent in a standalone load) does not prevent specs from loading it.
+          class Callable
+            # Keys the base Provider exposes as named kwargs for the
+            # completion operations. Anything else the fleet passes (sampling
+            # scalars, `temperature` — a Canonical::Params member, 05 O4) is
+            # folded into Canonical::Params at the dispatch boundary.
+            COMPLETION_NAMED_KEYS = %i[tools schema thinking tool_prefs headers].freeze
+            EMBED_NAMED_KEYS = %i[dimensions headers].freeze
+
+            def initialize(instance_cfg:, logger:, provider: nil)
+              @instance_cfg = instance_cfg
+              @logger = logger
+              @injected_provider = provider
+              @disconnected = false
+            end
+
+            def disconnected?
+              @disconnected
+            end
+
+            def disconnect
+              @disconnected = true
+              @provider&.disconnect
+              @logger.debug { '[openai][callable] disconnected' }
+            end
+
+            def provider
+              @provider ||= @injected_provider || Legion::Extensions::Llm::Openai::Provider.new(@instance_cfg)
+            end
+
+            # -- Fleet dispatch operations ----------------------------------------
+            # The fleet passes `model:` as the offering's raw model id (String).
+            # B4: the callable hands it to the wire unchanged — no wrapping, no
+            # default, no fallback. The 0.8.0 funnel renders `model:` verbatim
+            # into the payload, so a wrapped value would corrupt the request.
+
+            def chat(messages, model:, **rest)
+              # 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, &)
+              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)
+              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)
+              provider.enforce_canonical_messages!(messages)
+              _named, params = split_fleet_kwargs(rest, [])
+              provider.count_tokens(messages: messages, model: model, params: params)
+            end
+
+            def image(prompt:, model:, **rest)
+              provider.image(prompt: prompt, model: model, **rest)
+            end
+
+            def moderate(input:, model:, **rest)
+              provider.moderate(input: input, model: model, **rest)
+            end
+
+            def normalize_dispatch_error(error:)
+              reason = error.message.to_s[0, 512]
+
+              kind = case error
+                     when Faraday::ConnectionFailed
+                       :connection_failure
+                     when Faraday::TimeoutError
+                       :timeout
+                     when Faraday::ClientError
+                       classify_client_error(error: error)
+                     when Faraday::ServerError
+                       classify_server_error(error: error)
+                     when Legion::Extensions::Llm::OverloadedError
+                       :overloaded
+                     else
+                       # ServiceUnavailableError and all other error types map to
+                       # :provider_error. OpenAI does not produce a distinct flat
+                       # instance-down signal separate from overload; only an
+                       # authoritative explicit instance_unavailable condition
+                       # (which OpenAI does not emit via normal dispatch) would
+                       # map to :instance_unavailable.
+                       :provider_error
+                     end
+
+              Legion::Extensions::Llm::Routing::ProviderOutcome.new(
+                kind: kind,
+                reason: reason.empty? ? 'unknown dispatch error' : reason
+              )
+            end
+
+            private
+
+            # 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
+
+            def classify_client_error(error:)
+              status = error.respond_to?(:response_status) ? error.response_status : nil
+              case status
+              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:)
+              # NEVER classify raw 503/529/5xx as instance_unavailable by status alone.
+              # OpenAI 503 means overload/maintenance, not a permanent instance death.
+              status = error.respond_to?(:response_status) ? error.response_status : nil
+              case status
+              when 503, 529 then :overloaded
+              else :provider_error
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/openai/instance_discovery.rb

@@ -7,8 +7,9 @@ module Legion
         # Candidate collection and normalization for Openai.discover_instances.
         # Extracted from the Openai module to keep it within Metrics limits.
         # The synthetic instances.default entry (placeholder env:// key nested
-        # under credentials) can surface here without a top-level api_key; the
-        # discovery actor skips credential-less candidates (D3).
+        # under credentials) can surface here without a top-level api_key;
+        # dedup_and_log_candidates skips disabled and credential-less
+        # candidates so discover_instances only returns claimable instances.
         module InstanceDiscovery
           extend Legion::Logging::Helper
 
@@ -67,13 +68,25 @@ module Legion
           end
 
           def dedup_and_log_candidates(candidates)
-            discovered = CredentialSources.dedup_credentials(candidates)
-                                          .transform_values { |cfg| sanitize_instance_config(cfg) }
+            deduped = CredentialSources.dedup_credentials(candidates)
+            discovered = deduped.reject { |_, config| config[:enabled] == false || unresolved_credential?(config) }
+                                .transform_values { |cfg| sanitize_instance_config(cfg) }
             instance_names = discovered.keys.sort_by(&:to_s).join(', ')
             log.debug { "Discovered #{discovered.size} OpenAI provider instance candidate(s): #{instance_names}" }
             discovered
           end
 
+          # enabled: false is a skip, not a credential: a disabled instance is
+          # never claimed (the discovery pipeline reads this method as the
+          # single claimable source). A nil credential or an unresolved
+          # env:// / vault:// placeholder (the synthetic provider_settings
+          # default nests env://OPENAI_API_KEY) cannot authenticate and is
+          # never claimed.
+          def unresolved_credential?(config)
+            cred = config[:openai_api_key]
+            cred.nil? || cred.to_s.match?(%r{\A(vault|env)://})
+          end
+
           def settings_instances(config)
             return {} unless config.is_a?(Hash)