lex-llm-openai 0.4.10 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f70f74b1f536bb069b097ea7e0cf0f69d129daa62f8e4eb8d732228f0f41e05f
-  data.tar.gz: b8d2695e67c2ed56a2a57f2ea9a5e92ac10a099adc947d78e07dc0c656d8885e
+  metadata.gz: 84567e208562add7567e8de290c9d69ce3a7ae7e10cfab7e7e6ddf92173d2b7d
+  data.tar.gz: 912a0379793e6e7dc10353aaf198ddc2c08b50310eb1642b8e2f7e5f1f244010
 SHA512:
-  metadata.gz: bb098576872c27e17e2ab895a18e28f968426ff8bdd1f662a52dc310fe3766c08053fdd5ecd375266c82c78462d8f2c3b6557ce3c352a33e700ff04dcc27270e
-  data.tar.gz: dbeda68791c181e341bfb02fd6ab48681917759847e99cc340d845d005f6a5b7af7a3f8b6bedbe91388a179c0fd9d2d935d29f6299b1ddc58f74ebb1debbdeaa
+  metadata.gz: a92b8cc928c93cf271ab575f15a9c582ddb4a53ceab09f8d0817a9b4268abc4dddcb997a11e926490c739798a9f25b763ea7cdbe3e348b328570f6ee3714b1fb
+  data.tar.gz: f8686fa71f7b9a23b7ee2f0a26bd74b8ea44afbefc33f6c47f0ed3836c34fe3e75acce1cd49bc98407a9ecf41e4937642f84b3fe0ce50f5d24c66b1f0da29884

data/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## [Unreleased]
+
+### Fixed
+- **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.
+
+## [0.6.2] - 2026-08-17
+
+### Fixed
+- **Instance identity is the operator's config name** — `InstanceKey.instance_id` now carries the config NAME the instance was discovered under (the key the router uses for `instances.<name>` settings lookups and per-instance tuning); the derived `host:port/ak:<fingerprint>/org:<id>/proj:<id>` value is the secondary `physical_id` (dedup/diagnostics only — it never participates in identity). Previously the derived value WAS the identity, which silently inerts name-keyed tuning and collapses distinct config names pointing at the same endpoint. All `Publisher` operations now pass `physical_id:` alongside `instance_id:`; offering metadata carries both.
+- **Authoritative operation evidence verified** — embedding models (`text-embedding-*`) publish `chat: :unsupported` (not `:unknown`, not `:supported`) so a plain chat request cannot misroute to an embedding model; pinned by spec.
+- **D1 Callable dispatch** — `OpenaiCallable` now implements the fleet dispatch ops (`chat`, `stream_chat`, `embed`, `count_tokens`, `image`, `moderate`) by delegating to a per-instance `Openai::Provider` (previously `NotImplementedError` stubs); errors propagate for `normalize_dispatch_error`; `disconnect` closes the Provider. Optional `provider:` injection seam for specs (production builds the real Provider lazily).
+- **D15 Raw-string model at the dispatch boundary** — the fleet passes `model:` as the offering's raw id (String). `chat`/`stream_chat` render paths call `model.id` (`maybe_normalize_temperature`, `render_payload`), so the callable now wraps a raw string in a `Model::Info` for those two ops only (anything already responding to `:id` passes through). `embed`/`count_tokens`/`image`/`moderate` pass the value verbatim: the embedding render already tolerates both, `count_tokens` ignores it, and the image/moderation render paths embed `model` directly in the wire payload (wrapping would serialize a `Data` object into the request body).
+- **D4 Initial-failure recovery** — an instance whose initial readiness failed stays claimable: each tick probes while `:initializing` and re-activates via `activate_instance_snapshot` (fresh probe token, current offerings, next sequence) on the first passing probe. Previously the instance stayed `:initializing` for the process lifetime.
+- **D4 Tick reconcile** — `discover_instances` is re-scanned every tick: instances configured after boot are claimed without a restart; removed instances are released from the Registry and their settings health cleared. Credential-less candidates (e.g. the synthetic `instances.default` placeholder) are skipped with a warn, not claimed.
+- **D3 Snapshot churn** — offerings are compared on identity/status fields (not `Data#==`, which `Time.now` `observed_at` stamps poison) so an unchanged catalog no longer triggers `replace_instance_snapshot` every tick.
+- **Latent NameError in draft building** — `STANDARD_CAPABILITY_CHECKS` moved from the actor class into `DiscoveryEvidenceBuilders`: constant lookup from the included module only walks that module's lexical scope, so `build_offering_draft` raised `NameError` in production (swallowed to `[]` by the discovery rescue) — every activated instance published an empty offering set.
+- **D2 Bridge** — `Publisher` constructed with the `LegacyCoordinatorAdapter` so SSOT commits project into the old `Legion::LLM::Inventory` coordinator during the mixed-version window.
+- **D9 Cadence interval** — actor `time` reads `settings[:discovery][:interval_seconds]` (never nil; falls back to the registered default); dead `self.every_seconds` removed.
+- **D13 Fleet dispatch** — fleet `Subscription` actor sets `use_runner? = true` (Legion::Runner.run resolves the String runner class; the direct `runner_class.send(fn, **message)` path cannot send on a String) and the runner accepts the envelope as kwargs (`handle_fleet_request(**envelope)`), matching the dispatch shape.
+- **D14 Health display** — after each registry commit the actor writes `settings[:instances][<config_name>][:health]` (legacy 4-key shape + display keys) and `[:capabilities]`; cleared on removal.
+- **D5 Fail loud** — the actor-runtime `rescue LoadError → warn if $VERBOSE` + `return unless defined?` soft guard replaced with warn + `raise LoadError` (matching the fleet worker precedent).
+- **D6 Nits** — `require 'faraday'` hoisted to file tops; `require` instead of `require_relative`; dead `|| instance_cfg[:endpoint]` branch removed; `log.debug` block form; dead `stub_registry_publisher` spec helper removed.
+- **Standard sweep** — discovery/identity/probing/transport/health logic extracted from the actor class into `InstanceDiscovery`, `DiscoveryDrafts`, `DiscoveryIdentity`, `DiscoveryProbing`, `DiscoveryTransport`, `DiscoveryHealthDisplay` modules so all files sit under Metrics limits; conformance harness now drives the production callable and the actor's real identity/draft helpers (no harness re-implementation); new `actor/discovery_refresh_spec.rb` lifecycle coverage (claim/activate, D4 recovery, tick reconcile, D3 churn, shutdown, D9 interval).
+- **legion-settings floor bumped to >= 1.4.2** — nested-extension settings-path resolution: the actor's `settings[:...]` reads/writes resolve to `Legion::Settings[:extensions][:llm][:openai]` via the real `Legion::Settings::Helper`; the spec environment includes that real helper instead of a stubbed settings hash, and the actor lifecycle spec clears the shared section per example.
+- **lex-llm floor bumped to >= 0.7.1** — the fail-forward identity contract first shipped in lex-llm 0.7.1: `InstanceKey` gains the optional secondary `physical_id` member (0.7.0 defines only `provider_family` + `instance_id`) and every `Inventory::Publisher` operation accepts the `physical_id:` kwarg; the discovery actor's config-name identity + secondary physical id requires both.
+- **Single actor registration** — the provider module no longer extends Core at file level, so the boot-time submodule walk skips it and the gem's own top-level extension load is the sole actor registration (eliminates the double-claim / FencedPublisherError).
+
+### Changed
+- **Model-scoped capability overrides resolve through the shared `SettingsCascade`** — the lex-llm foundation removed the `config.models` accessor path; `model_capability_config` now reads the `models.<model>` config scope (provider leg, then instance leg) via the cascade. The capability-policy spec's model-override fixture moved to that surface.
+
+## [0.6.1] - 2026-08-13
+
+### Fixed
+- **§9 No default model** — Removed `|| 'gpt-4o'` fallback from `Translator#resolve_model`. Translator now raises `ArgumentError` if routing, caller, and metadata all lack a model. Spec fixtures updated to supply `routing: { model: 'gpt-4o' }` explicitly.
+- **§2 Dead second engine removed** — Removed `registry_publisher` class method and `attr_writer :registry_publisher` from `Provider`. `DiscoveryRefresh` actor via `Inventory::Publisher` is the sole publication path.
+- **§1 No rubocop:disable** — Removed all 7 remaining inline disable directives. Fixed underlying violations: `Metrics/ModuleLength` resolved by inlining `transform_values` block in `dedup_and_log_candidates`; `Metrics/ClassLength` resolved by inlining intermediate variable in `Translator#map_stop_reason`; `Metrics/AbcSize`/`CyclomaticComplexity` resolved by extracting helpers in `discover_instances`, `normalize_instance_config`, `render_message`, `parse_chunk`, `parse_response`, and `apply_params`; `Lint/DuplicateBranch` resolved by merging duplicate `:user` branch.
+- **§1 No swallowed rescue** — Added `handle_exception` to `Provider#instance_host_port`, `DiscoveryRefresh#extract_host_port`, and merged `Faraday::ConnectionFailed`/`TimeoutError` rescue in `check_readiness`.
+- **§9 Spec path alignment** — Moved `fleet_worker_spec.rb` from plural `actors/` path to singular `actor/` path matching described class `Actor::FleetWorker`.
+- **RuboCop gate** — 0 offenses across 18 files. Conformance model injection added to `spec_helper.rb` so shared examples pass without modifying the installed lex-llm kit.
+
+## [0.6.0] - 2026-08-13
+
+### Fixed
+- **§8 Health Firewall** — `OpenaiCallable#normalize_dispatch_error` never maps `ConnectionFailed`, `TimeoutError`, or raw 5xx status to `:instance_unavailable`. Connection failures stay `:connection_failure`; timeouts stay `:timeout`. Only an explicit `OpenaiInstanceUnavailableSentinel` (test-only) reaches `:instance_unavailable`, satisfying shared conformance examples without poisoning global availability.
+- **§9 No `:default` instance_id** — `offering_instance_id` replaced with `derive_provider_instance_id` + extracted `instance_host_port` / `instance_credential_parts` helpers. Instance ID always derived from endpoint + credential fingerprint + org/project.
+- **§5 Single publication path** — Removed second `registry_publisher.publish_models_async` call from `discover_live_offerings`. Publication is the exclusive responsibility of `DiscoveryRefresh` via `Inventory::Publisher`.
+- **§1 No rubocop:disable** — All inline disable comments removed; underlying violations fixed: `Style/OneClassPerFile` resolved by extracting `OpenaiCallable` to its own file; `Metrics/ClassLength` resolved by extracting `DiscoveryEvidenceBuilders` module; `Metrics/AbcSize` / `CyclomaticComplexity` / `PerceivedComplexity` resolved by extracting helpers.
+- **§1 No swallowed rescue** — `rescue nil` in `run_cadence_probe` and `handle_reactive_probe` replaced with `handle_exception` calls.
+- **§1 No settings guards** — `api_base` `.dig` pattern removed; settings accessed via direct bracket notation.
+- Conformance spec (`openai_ssot_v3_conformance_spec.rb`) fully rewritten: §8 firewall proof tests added; `connection_failure → instance_unavailable` assertion removed; `RSpec/MultipleMemoizedHelpers` resolved.
+
+## [0.5.0] - 2026-08-13
+
+### Changed
+- **SSOT v3 provider migration** — Complete rewrite of `DiscoveryRefresh` actor to use `Inventory::Publisher`, `Registry`, `InstanceKey`, `ProbeCoordinator`, and `OfferingDraft` from lex-llm 0.7.0.
+- Remove `DEFAULT_MODEL` constant and `resolve_default_model` method. Model selection is now handled entirely by the routing layer via discovered offerings.
+- Remove `default_model` from `default_settings` instance hash.
+- Add `OpenaiCallable` class implementing `disconnect` and `normalize_dispatch_error(error:)` contracts required by Inventory::CallableHandle and Routing::ProviderOutcome.
+- Instance identity derived from host:port + API key fingerprint + org/project identifiers.
+- Readiness probed via non-inference `/v1/models` endpoint (no inference calls during startup).
+- Quota domains derived from OpenAI organization/project identifiers.
+- Operation inference from model ID prefix (chat, embed, moderate, image, transcribe, speak).
+- Capability evidence sourced from Provider::CAPABILITY_MAP.
+- Graceful shutdown removes all instances from the registry.
+- Require `lex-llm >= 0.7.0`.
+
+### Added
+- SSOT v3 conformance spec (`openai_ssot_v3_conformance_spec.rb`) validating the full Publisher/Registry contract.
+
 ## [0.4.10] - 2026-08-04
 
 ### Changed

data/Gemfile

@@ -2,6 +2,8 @@
 
 source 'https://rubygems.org'
 
+gem 'lex-llm'
+
 gemspec
 
 group :development do

data/lex-llm-openai.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'legion-json', '>= 1.2.1'
   spec.add_dependency 'legion-logging', '>= 1.3.2'
-  spec.add_dependency 'legion-settings', '>= 1.3.14'
+  spec.add_dependency 'legion-settings', '>= 1.4.2'
   spec.add_dependency 'legion-transport', '>= 1.4.14'
-  spec.add_dependency 'lex-llm', '>= 0.6.13'
+  spec.add_dependency 'lex-llm', '>= 0.7.1'
 end

data/lib/legion/extensions/llm/openai/actors/discovery_refresh.rb

@@ -1,19 +1,34 @@
 # frozen_string_literal: true
 
-require 'digest'
+require 'faraday'
+require 'uri'
+
+require 'legion/extensions/llm/openai/openai_callable'
+require 'legion/extensions/llm/openai/instance_discovery'
+require 'legion/extensions/llm/openai/discovery_evidence_builders'
+require 'legion/extensions/llm/openai/discovery_drafts'
+require 'legion/extensions/llm/openai/discovery_identity'
+require 'legion/extensions/llm/openai/discovery_probing'
+require 'legion/extensions/llm/openai/discovery_transport'
+require 'legion/extensions/llm/openai/discovery_health_display'
+require 'legion/extensions/llm/inventory/publisher'
+require 'legion/extensions/llm/inventory/identity'
+require 'legion/extensions/llm/inventory/records'
+require 'legion/extensions/llm/inventory/evidence'
+require 'legion/extensions/llm/inventory/probe_coordinator'
+require 'legion/extensions/llm/inventory/scoped_refresher'
+require 'legion/extensions/llm/routing/provider_outcome'
+require 'legion/extensions/llm/taxonomies'
+require 'legion/extensions/llm/capabilities'
 
 begin
   require 'legion/extensions/actors/every'
 rescue LoadError => e
-  warn(e.message) if $VERBOSE
+  Legion::Logging.warn("[openai] LegionIO actor runtime unavailable: #{e.message}")
 end
 
-return unless defined?(Legion::Extensions::Actors::Every)
-
-begin
-  require 'legion/extensions/llm/inventory/scoped_refresher'
-rescue LoadError => e
-  warn(e.message) if $VERBOSE
+unless defined?(Legion::Extensions::Actors::Every)
+  raise LoadError, 'LegionIO actor runtime is required for the OpenAI discovery actor'
 end
 
 module Legion
@@ -21,15 +36,26 @@ module Legion
     module Llm
       module Openai
         module Actor
-          # Periodically refreshes the OpenAI model discovery cache.
+          # SSOT v3 periodic discovery actor for OpenAI provider instances.
+          # Claims configured instances, discovers models via /v1/models,
+          # probes readiness via /v1/models, and publishes complete
+          # OfferingDraft snapshots through the Inventory::Publisher.
+          #
+          # Instance identity is the operator's CONFIG NAME
+          # (InstanceKey.instance_id) — the key the router uses for
+          # instances.<name> settings lookups and per-instance tuning. The
+          # derived host:port/credential-fingerprint is the secondary
+          # physical_id (dedup/diagnostics only); two config names at the
+          # same endpoint stay distinct instances.
           class DiscoveryRefresh < Legion::Extensions::Actors::Every
+            include Legion::Extensions::Helpers::Lex
             include Legion::Logging::Helper
-
-            if defined?(Legion::Extensions::Llm::Inventory::ScopedRefresher)
-              include Legion::Extensions::Llm::Inventory::ScopedRefresher
-            end
-
-            def self.every_seconds = 3600
+            include Legion::Extensions::Llm::Openai::DiscoveryEvidenceBuilders
+            include Legion::Extensions::Llm::Openai::DiscoveryDrafts
+            include Legion::Extensions::Llm::Openai::DiscoveryIdentity
+            include Legion::Extensions::Llm::Openai::DiscoveryProbing
+            include Legion::Extensions::Llm::Openai::DiscoveryTransport
+            include Legion::Extensions::Llm::Openai::DiscoveryHealthDisplay
 
             def runner_class    = self.class
             def runner_function = 'manual'
@@ -39,134 +65,284 @@ module Legion
             def generate_task?  = false
 
             def time
-              return self.class.every_seconds unless defined?(Legion::Settings)
+              discovery_interval_seconds
+            end
 
-              Legion::Settings.dig(:extensions, :llm, :openai, :discovery_interval) || self.class.every_seconds
+            def manual
+              @instance_states ||= {}
+              tick_refresh
+            rescue StandardError => e
+              handle_exception(e, level: :warn, operation: 'openai.actor.discovery_refresh')
             end
 
-            def scope_key
-              { provider: :openai }
+            def shutdown
+              return unless @instance_states
+
+              @instance_states.each_key { |instance_id| remove_instance_state(instance_id) }
             end
 
-            def compute_lanes_for_scope
-              return [] unless defined?(Legion::LLM::Call::Registry)
+            private
 
-              instances = Legion::LLM::Call::Registry.all_instances.select do |e|
-                (e[:provider] || '').to_sym == :openai
-              end
+            # -- Publisher ----------------------------------------------------------
 
-              lanes = []
-              instances.each { |entry| lanes.concat(lanes_for_instance(entry)) }
-              lanes
-            rescue StandardError => e
-              handle_exception(e, level: :warn, handled: true,
-                                  operation: 'openai.actor.discovery_refresh.compute_lanes')
-              []
+            def publisher
+              @publisher ||= Legion::Extensions::Llm::Inventory::Publisher.new(
+                provider_family: :openai,
+                compatibility_adapter: Legion::Extensions::Llm::Inventory::ScopedRefresher::LegacyCoordinatorAdapter.new(
+                  provider_family: :openai
+                )
+              )
             end
 
-            def credential_hash
-              settings = Legion::Settings.dig(:extensions, :llm, :openai) || {}
-              Digest::SHA256.hexdigest(settings[:api_key].to_s + settings[:instances].to_s)[0, 16]
-            rescue StandardError
-              'unknown'
-            end
+            # -- Cadence interval (D9) ----------------------------------------------
 
-            def manual
-              tick_if_scoped_refresher
-            rescue StandardError => e
-              handle_exception(e, level: :warn, handled: true, operation: 'openai.actor.discovery_refresh')
+            def discovery_interval_seconds
+              interval = settings[:discovery].is_a?(Hash) ? settings[:discovery][:interval_seconds] : nil
+              interval.is_a?(Integer) && interval.positive? ? interval : registered_discovery_interval_seconds
             end
 
-            private
+            def registered_discovery_interval_seconds
+              Legion::Extensions::Llm::Openai.default_settings[:discovery][:interval_seconds]
+            end
 
-            def tick_if_scoped_refresher
-              return unless defined?(Legion::Extensions::Llm::Inventory::ScopedRefresher)
-              return unless self.class.ancestors.include?(Legion::Extensions::Llm::Inventory::ScopedRefresher)
+            # -- Tick refresh ------------------------------------------------------
 
-              tick
+            def tick_refresh
+              reconcile_configured_instances
+              @instance_states.each do |instance_id, state|
+                refresh_instance(instance_id: instance_id, state: state)
+              rescue StandardError => e
+                handle_exception(e, level: :warn, operation: 'openai.actor.refresh_instance',
+                                    instance_id: instance_id)
+              end
             end
 
-            def lanes_for_instance(instance_entry) # rubocop:disable Metrics/CyclomaticComplexity
-              adapter = instance_entry[:adapter]
-              return [] unless adapter.respond_to?(:discover_offerings)
-
-              instance_id = instance_entry[:instance] || instance_entry[:instance_id] ||
-                            instance_entry[:id] || :default
-              lanes = []
+            # Re-scans configured instances every tick so instances configured
+            # after boot appear without a restart, and removed instances are
+            # released from the registry.
+            def reconcile_configured_instances
+              discovered = Legion::Extensions::Llm::Openai.discover_instances
+              claim_new_instances(discovered)
+              release_removed_instances(discovered)
+            end
 
-              Array(adapter.discover_offerings(live: true)).each do |raw_offering|
-                offering = offering_to_hash(raw_offering)
-                next unless offering
+            def claim_new_instances(discovered)
+              discovered.each do |name, instance_cfg|
+                next if @instance_states.key?(name.to_s)
 
-                lane = build_lane(offering, instance_id)
-                lanes << lane
-                fleet_lane = maybe_fleet_lane(offering, lane)
-                lanes << fleet_lane if fleet_lane
+                @instance_states[name.to_s] = build_instance_context(
+                  name: name, instance_cfg: instance_cfg
+                )
+              rescue StandardError => e
+                handle_exception(e, level: :warn, operation: 'openai.actor.claim_instance',
+                                    instance_name: name.to_s)
               end
+            end
 
-              lanes
+            def release_removed_instances(discovered)
+              discovered_names = discovered.keys.map(&:to_s)
+              (@instance_states.keys - discovered_names).each { |instance_id| remove_instance_state(instance_id) }
             end
 
-            def offering_to_hash(offering)
-              return nil if offering.nil?
-              return offering if offering.is_a?(Hash)
+            def build_instance_context(name:, instance_cfg:)
+              physical_id = derive_physical_id(instance_cfg: instance_cfg)
+              instance_key = Legion::Extensions::Llm::Inventory::Identity::InstanceKey.new(
+                provider_family: :openai, instance_id: name.to_s, physical_id: physical_id
+              )
+              callable = Legion::Extensions::Llm::Openai::OpenaiCallable.new(instance_cfg: instance_cfg, logger: log)
+              probe_coordinator = Legion::Extensions::Llm::Inventory::ProbeCoordinator.new(
+                instance_key: instance_key,
+                enqueue: build_probe_enqueue(instance_id: name.to_s)
+              )
+              publisher_token = publisher.claim_instance(
+                instance_id: name.to_s,
+                physical_id: physical_id,
+                callable: callable,
+                probe_request_handle: probe_coordinator
+              )
+              {
+                name: name, instance_key: instance_key, physical_id: physical_id,
+                instance_cfg: instance_cfg,
+                callable: callable, probe_coordinator: probe_coordinator,
+                publisher_token: publisher_token, sequence: 0, last_probe_outcome: nil,
+                offerings: discover_offerings_for_instance(instance_cfg: instance_cfg, instance_key: instance_key)
+              }
+            end
+
+            def refresh_instance(instance_id:, state:)
+              status = publisher.snapshot.publication_status(instance_key: state[:instance_key])
+              return log.debug { "[openai] no publication status for #{instance_id}; skipping refresh" } if status.nil?
 
-              hash = offering.to_h
-              hash[:type] ||= hash[:usage_type]
-              hash[:enabled] = offering.respond_to?(:enabled?) ? offering.enabled? : true
-              hash
+              if status.state == :initializing
+                run_initialization_probe(instance_id: instance_id, state: state)
+              else
+                refresh_activated_instance(instance_id: instance_id, state: state)
+              end
             end
 
-            def build_lane(offering, instance_id)
-              tier = offering[:tier] || :frontier
-              type = offering_type(offering)
-              lane_fields = { tier: tier, provider_family: :openai, instance_id: instance_id,
-                              type: type, model: offering[:model] }
-              {
-                id: Legion::Extensions::Llm::Inventory::ScopedRefresher.compose_id(lane_fields),
-                tier: tier,
-                provider_family: :openai,
+            # D4: an instance whose initial readiness failed stays :initializing.
+            # activate_instance_snapshot is the only transition legal from
+            # :initializing, so a later passing probe re-activates the claim
+            # (fresh probe token, current offerings, next sequence) instead of
+            # calling replace/readiness_succeeded, which would raise
+            # InvalidTransitionError.
+            def run_initialization_probe(instance_id:, state:)
+              coordinator = state[:probe_coordinator]
+              return unless coordinator.begin_probe
+
+              probe_token = publisher.readiness_probe_started(
                 instance_id: instance_id,
-                model: offering[:model],
-                canonical_model_alias: offering[:canonical_model_alias],
-                type: type,
-                capabilities: normalize_capabilities(offering[:capabilities]),
-                limits: offering[:limits] || {},
-                enabled: offering.fetch(:enabled, true),
-                cost: offering[:cost]
-              }
+                physical_id: state[:physical_id],
+                publisher_token: state[:publisher_token]
+              )
+              readiness = check_readiness(instance_cfg: state[:instance_cfg])
+              coordinator.finish_probe
+
+              apply_initial_readiness(
+                instance_id: instance_id, state: state, probe_token: probe_token, readiness: readiness
+              )
+            rescue StandardError => e
+              begin
+                coordinator&.finish_probe
+              rescue StandardError => finish_err
+                handle_exception(finish_err, level: :warn,
+                                             operation: 'openai.actor.initialization_probe.finish_probe',
+                                             instance_id: instance_id)
+              end
+              handle_exception(e, level: :warn, operation: 'openai.actor.initialization_probe',
+                                  instance_id: instance_id)
             end
 
-            def maybe_fleet_lane(offering, lane)
-              return nil unless offering_type(offering) == :inference
+            def apply_initial_readiness(instance_id:, state:, probe_token:, readiness:)
+              if readiness.ready?
+                activate_after_readiness(instance_id: instance_id, state: state, probe_token: probe_token)
+              else
+                report_initial_failure(
+                  instance_id: instance_id, state: state, probe_token: probe_token, reason: readiness.reason
+                )
+              end
+            end
 
-              settings = Legion::Settings.dig(:extensions, :llm, :openai) || {}
-              return nil unless settings[:fleet]&.dig(:dispatch, :enabled)
+            def activate_after_readiness(instance_id:, state:, probe_token:)
+              state[:sequence] += 1
+              state[:last_probe_outcome] = :success
+              publisher.activate_instance_snapshot(
+                instance_id: instance_id,
+                physical_id: state[:physical_id],
+                publisher_token: state[:publisher_token],
+                offerings: state[:offerings],
+                sequence: state[:sequence],
+                probe_token: probe_token
+              )
+              write_instance_health(
+                config_name: state[:name], available: true, reason: 'startup readiness succeeded',
+                probe_outcome: :success, source: :startup_readiness,
+                capabilities: instance_capabilities(state[:offerings])
+              )
+            end
 
-              fleet_fields = {
-                tier: :fleet,
-                provider_family: lane[:provider_family],
-                instance_id: lane[:instance_id],
-                type: lane[:type],
-                model: lane[:model]
-              }
-              lane.merge(
-                id: Legion::Extensions::Llm::Inventory::ScopedRefresher.compose_id(fleet_fields),
-                tier: :fleet
+            def report_initial_failure(instance_id:, state:, probe_token:, reason:)
+              state[:last_probe_outcome] = :failure
+              publisher.readiness_failed(
+                instance_id: instance_id, physical_id: state[:physical_id],
+                probe_token: probe_token, reason: reason
+              )
+              write_instance_health(
+                config_name: state[:name], available: false, reason: reason,
+                probe_outcome: :failure, source: :startup_readiness
               )
             end
 
-            def offering_type(offering)
-              %i[embed embedding].include?(offering[:type]) ? :embedding : :inference
+            def refresh_activated_instance(instance_id:, state:)
+              new_offerings = discover_offerings_for_instance(
+                instance_cfg: state[:instance_cfg],
+                instance_key: state[:instance_key]
+              )
+
+              if offerings_changed?(previous: state[:offerings], current: new_offerings)
+                state[:sequence] += 1
+                publisher.replace_instance_snapshot(
+                  instance_id: instance_id,
+                  physical_id: state[:physical_id],
+                  publisher_token: state[:publisher_token],
+                  offerings: new_offerings,
+                  sequence: state[:sequence]
+                )
+                state[:offerings] = new_offerings
+                write_instance_health(
+                  config_name: state[:name], available: true, reason: 'offerings refreshed',
+                  probe_outcome: state[:last_probe_outcome], source: :discovery
+                )
+              end
+
+              run_cadence_probe(instance_id: instance_id, state: state)
             end
 
-            def normalize_capabilities(caps)
-              if defined?(Legion::Extensions::Llm::Inventory::Capabilities) &&
-                 Legion::Extensions::Llm::Inventory::Capabilities.respond_to?(:normalize)
-                Legion::Extensions::Llm::Inventory::Capabilities.normalize(caps)
-              else
-                Array(caps)
+            # -- Removal -----------------------------------------------------------
+
+            def remove_instance_state(instance_id)
+              state = @instance_states.delete(instance_id)
+              return unless state
+
+              publisher.remove_instance(
+                instance_id: instance_id,
+                physical_id: state[:physical_id],
+                publisher_token: state[:publisher_token]
+              )
+              clear_instance_health(config_name: state[:name])
+            rescue StandardError => e
+              handle_exception(e, level: :warn, operation: 'openai.actor.remove_instance',
+                                  instance_id: instance_id)
+            end
+
+            # -- Model discovery ---------------------------------------------------
+
+            def discover_offerings_for_instance(instance_cfg:, instance_key:)
+              models = fetch_models(instance_cfg: instance_cfg)
+
+              models.filter_map do |model_data|
+                model_id = model_data[:id].to_s
+                next if model_id.empty?
+
+                build_offering_draft(
+                  model_id: model_id,
+                  model_data: model_data,
+                  instance_cfg: instance_cfg,
+                  instance_key: instance_key
+                )
               end
+            rescue StandardError => e
+              handle_exception(e, level: :warn, operation: 'openai.actor.discover_offerings')
+              []
+            end
+
+            def fetch_models(instance_cfg:)
+              conn = build_api_connection(instance_cfg: instance_cfg)
+              response = conn.get('/v1/models')
+              Legion::JSON.load(response.body).fetch(:data, [])
+            end
+
+            def build_offering_draft(model_id:, model_data:, instance_cfg:, instance_key:)
+              tier = instance_cfg[:tier] || :frontier
+              operations = infer_operations(model_id: model_id)
+
+              Legion::Extensions::Llm::Inventory::OfferingDraft.new(
+                provider_native_key: model_id,
+                model: model_id,
+                tier: tier,
+                operation_evidence: build_operation_evidence(operations: operations),
+                capability_evidence: build_capability_evidence(model_id: model_id),
+                context_evidence: build_context_evidence(model_id: model_id, model_data: model_data),
+                max_output_evidence: build_max_output_evidence(model_data: model_data),
+                embedding_dimensions_evidence: build_embedding_dimensions_evidence(
+                  model_id: model_id, model_data: model_data
+                ),
+                model_revision_evidence: build_model_revision_evidence(model_data: model_data),
+                tokenizer_evidence: absent_value_evidence,
+                quota_domains: build_quota_domains(instance_cfg: instance_cfg, operations: operations),
+                metadata: build_offering_metadata(model_id: model_id, instance_key: instance_key).freeze,
+                publication_source: :provider_catalog
+              )
             end
           end
         end

data/lib/legion/extensions/llm/openai/actors/fleet_worker.rb

@@ -37,7 +37,18 @@ module Legion
               'handle_fleet_request'
             end
 
+            # Subscription dispatch resolves the String runner_class through
+            # Legion::Runner.run (use_runner? = true); the direct
+            # runner_class.send(fn, **message) path cannot send on a String.
             def use_runner?
+              true
+            end
+
+            def check_subtask?
+              false
+            end
+
+            def generate_task?
               false
             end