openfeature-sdk 0.6.6 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 500c09c5333475a75aeff77cdab714c1360f4c14a84c28f9f16fe3b0dc42cb8f
-  data.tar.gz: 4d760e25308fad1ea762e8547260f87dea3474a8861eadd25993cfd2dde55b04
+  metadata.gz: 1b8b6e8a5fd01205278fa44c809eb3c1ef578b56e5542aa94793a090e605458d
+  data.tar.gz: f85c7d0e8b804fb651e02cc3c59d14c21458f9fdb419d58df6d8fbb714a35b9b
 SHA512:
-  metadata.gz: 4bfda5295966ab245426ecaa0d2dbb440b7f273833193906b9fd91fd6ffeb41e5b49e652a9d05dbf6679c08cfc434c4733d34384dfc1d64be995194f3938cdf1
-  data.tar.gz: 2359651d7407cdd30e41e15e4d764efc47565e025b2046adbc4942da0c25d62396bd5e52991626d728b675b123aa52bcce733f8ebc71703112ebe77d6704e96e
+  metadata.gz: a7fef199498fb02863ed74cf76a6fbff8acf65df23e2e5d4baad90b6ed3da589b6ca98da1540443a7367456a527819eb2380979aa4f1a1ef8780c33ccf425d32
+  data.tar.gz: 71db2db0d85592861ebd5f117d7599e9d54374deb9a6eae5060716044abddb27a4bd10db7ca07314540a36adeb7c366afa1a8c21fb4f19824e05e15fd59a1a27

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.6.6"
+  ".": "0.7.0"
 }

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.7.0](https://github.com/open-feature/ruby-sdk/compare/v0.6.7...v0.7.0) (2026-10-23)
+
+
+### ⚠ BREAKING CHANGES
+
+* resolve a client's provider by domain on every call ([#352](https://github.com/open-feature/ruby-sdk/issues/352))
+
+### Features
+
+* let providers own their lifecycle events ([#353](https://github.com/open-feature/ruby-sdk/issues/353)) ([15faf98](https://github.com/open-feature/ruby-sdk/commit/15faf98d1c900118da362f6b8d76ccdec1b3b99e))
+
+
+### Bug Fixes
+
+* catch NotImplementedError in track and the hook lifecycle ([#349](https://github.com/open-feature/ruby-sdk/issues/349)) ([62759f4](https://github.com/open-feature/ruby-sdk/commit/62759f443fa8cb2f7a1b67720397240063623da1))
+* deliver provider events in order, outside handler locks ([#351](https://github.com/open-feature/ruby-sdk/issues/351)) ([16bf89c](https://github.com/open-feature/ruby-sdk/commit/16bf89cf72541c22de9565f0dcdbfcf9dfe097ad))
+* release init waiters on replacement and same-thread re-entry ([#348](https://github.com/open-feature/ruby-sdk/issues/348)) ([9e82b15](https://github.com/open-feature/ruby-sdk/commit/9e82b15e9730f0c53f2186aeb39cc53275d5f929))
+* resolve a client's provider by domain on every call ([#352](https://github.com/open-feature/ruby-sdk/issues/352)) ([fa0076f](https://github.com/open-feature/ruby-sdk/commit/fa0076fb8a159a180af408ee0a335e9f8d43afc9))
+
+## [0.6.7](https://github.com/open-feature/ruby-sdk/compare/v0.6.6...v0.6.7) (2026-10-23)
+
+
+### Features
+
+* pass the bound domain to provider init and support domain-scoped providers ([#345](https://github.com/open-feature/ruby-sdk/issues/345)) ([f3cf6b7](https://github.com/open-feature/ruby-sdk/commit/f3cf6b76c06297aa4c0a2a95ea1055f816269e3b))
+
+
+### Bug Fixes
+
+* return defaults instead of raising from client calls ([#346](https://github.com/open-feature/ruby-sdk/issues/346)) ([481f21c](https://github.com/open-feature/ruby-sdk/commit/481f21cfe70365de92c6ece3eb92c40117a7e1c5))
+
 ## [0.6.6](https://github.com/open-feature/ruby-sdk/compare/v0.6.5...v0.6.6) (2026-10-22)
 
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openfeature-sdk (0.6.6)
+    openfeature-sdk (0.7.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -17,8 +17,8 @@
   </a>
   <!-- x-release-please-start-version -->
 
-  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.6.6">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.6&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.7.0">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.7.0&color=blue&style=for-the-badge" />
   </a>
 
   <!-- x-release-please-end -->
@@ -287,6 +287,7 @@ Log output uses a structured key=value format:
 
 Clients can be assigned to a domain. A domain is a logical identifier which can be used to associate clients with a particular provider.
 If a domain has no associated provider, the default provider is used.
+Clients look up their domain's provider on every call, so a client created before `set_provider` follows the new binding.
 
 ```ruby
 OpenFeature::SDK.configure do |config|
@@ -300,28 +301,35 @@ legacy_flag_client = OpenFeature::SDK.build_client(domain: "legacy_flags")
 ### Eventing
 
 Events allow you to react to state changes in the provider or underlying flag management system, such as flag definition changes, provider readiness, or error conditions.
-Initialization events (`PROVIDER_READY` on success, `PROVIDER_ERROR` on failure) are dispatched for every provider.
-Some providers support additional events, such as `PROVIDER_CONFIGURATION_CHANGED`.
+Providers emit initialization events (`PROVIDER_READY` on success, `PROVIDER_ERROR` on failure) from `init`.
+A provider without `init` is `READY` as soon as it's registered, and its `PROVIDER_READY` handlers run before `set_provider` returns.
+For providers that define `init` but not `emits_lifecycle_events?` returning `true`, the SDK emits `PROVIDER_READY` after `init` returns and `PROVIDER_ERROR` if it raises.
+That path is deprecated (spec Appendix E), and the SDK logs a deprecation warning once per provider class to its configured logger.
+Handlers for events a provider emits from `init` run while `init` is still in progress, so they can't call `set_provider_and_wait` for that same provider.
+Some providers emit additional events: `PROVIDER_CONFIGURATION_CHANGED`, `PROVIDER_STALE`, `PROVIDER_RECONCILING` and `PROVIDER_CONTEXT_CHANGED`.
+Handlers receive a hash with the `provider_name` and any details the provider sent, such as `message` or `error_code`.
 
 Please refer to the documentation of the provider you're using to see what events are supported.
 
 ```ruby
 # Register event handlers at the API (global) level
 ready_handler = ->(event_details) do
-  puts "Provider #{event_details[:provider].metadata.name} is ready!"
+  puts "Provider #{event_details[:provider_name]} is ready!"
 end
 
 OpenFeature::SDK.add_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY, ready_handler)
 
-# The SDK automatically emits lifecycle events. Providers can emit additional spontaneous events
-# using the EventEmitter mixin to signal internal state changes like configuration updates.
+# Providers emit events using the EventEmitter mixin: lifecycle events from init, and spontaneous
+# events to signal internal state changes like configuration updates.
 class MyEventAwareProvider
   include OpenFeature::SDK::Provider::EventEmitter
 
+  def emits_lifecycle_events? = true
+
   def init(evaluation_context)
     # Start background process to monitor for configuration changes
-    # Note: SDK automatically emits PROVIDER_READY when init completes successfully
     start_background_process
+    emit_event(OpenFeature::SDK::ProviderEvent::PROVIDER_READY)
   end
 
   def start_background_process
@@ -351,6 +359,9 @@ This should only be called when your application is in the process of shutting d
 OpenFeature::SDK.shutdown
 ```
 
+The SDK also shuts down a replaced provider once no domain uses it.
+Events from shut-down providers are ignored.
+
 Individual providers can implement a `shutdown` method to perform cleanup:
 
 ```ruby
@@ -442,11 +453,29 @@ You’ll then need to write the provider by implementing the `Provider` duck.
 
 ```ruby
 class MyProvider
-  def init
-    # Perform any initialization steps with flag management system here
+  include OpenFeature::SDK::Provider::EventEmitter
+
+  # Tells the SDK that init emits PROVIDER_READY/PROVIDER_ERROR itself.
+  def emits_lifecycle_events? = true
+
+  # Optional: a provider without init is READY as soon as it's registered.
+  # Both arguments are optional; declare only the ones you need.
+  # `domain` is the domain the provider was bound to, or nil for the default provider.
+  def init(evaluation_context = nil, domain: nil)
+    # Perform any initialization steps with flag management system here, then emit PROVIDER_READY.
     # Return value is ignored
     # **Note** The OpenFeature spec defines a lifecycle method called `initialize` to be called when a new provider is set.
     # To avoid conflicting with the Ruby `initialize` method, this method should be named `init` when creating a provider.
+    emit_event(OpenFeature::SDK::ProviderEvent::PROVIDER_READY)
+  rescue => e
+    emit_event(OpenFeature::SDK::ProviderEvent::PROVIDER_ERROR, error_code: OpenFeature::SDK::Provider::ErrorCode::GENERAL, message: e.message)
+    raise
+  end
+
+  # Optional: return true if this provider keeps state for a single domain.
+  # The SDK then raises ArgumentError if the same instance is bound to a second domain.
+  def domain_scoped?
+    false
   end
 
   def shutdown

data/lib/open_feature/sdk/api.rb

@@ -48,11 +48,7 @@ module OpenFeature
       end
 
       def build_client(domain: nil, evaluation_context: nil)
-        active_provider = provider(domain:).nil? ? Provider::NoOpProvider.new : provider(domain:)
-
-        Client.new(provider: active_provider, domain:, evaluation_context:)
-      rescue
-        Client.new(provider: Provider::NoOpProvider.new, evaluation_context:)
+        Client.new(domain:, evaluation_context:)
       end
 
       def provider_metadata(domain: nil)

data/lib/open_feature/sdk/client.rb

@@ -17,11 +17,11 @@ module OpenFeature
       SUFFIXES = %i[value details].freeze
       EMPTY_HINTS = Hooks::Hints.new.freeze
 
-      attr_reader :metadata, :evaluation_context
+      attr_reader :metadata
 
-      attr_accessor :hooks
+      attr_accessor :hooks, :evaluation_context
 
-      def initialize(provider:, domain: nil, evaluation_context: nil)
+      def initialize(provider: nil, domain: nil, evaluation_context: nil)
         @provider = provider
         @metadata = ClientMetadata.new(domain:)
         @evaluation_context = evaluation_context
@@ -33,7 +33,7 @@ module OpenFeature
       end
 
       def provider_status
-        OpenFeature::SDK.configuration.provider_state(@provider)
+        OpenFeature::SDK.configuration.provider_state(resolve_provider)
       end
 
       def add_handler(event_type, handler = nil, &block)
@@ -51,17 +51,21 @@ module OpenFeature
       # Records a tracking event. If the provider does not implement
       # tracking, this is a no-op (spec 6.1.4).
       def track(tracking_event_name, evaluation_context: nil, tracking_event_details: nil)
-        return unless @provider.respond_to?(:track)
+        provider = resolve_provider
+        return unless provider.respond_to?(:track)
 
         built_context = build_evaluation_context(evaluation_context)
 
-        @provider.track(tracking_event_name, evaluation_context: built_context, tracking_event_details: tracking_event_details)
+        provider.track(tracking_event_name, evaluation_context: built_context, tracking_event_details: tracking_event_details)
+      rescue StandardError, NotImplementedError
+        nil
       end
 
       RESULT_TYPE.each do |result_type|
         SUFFIXES.each do |suffix|
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
             def fetch_#{result_type}_#{suffix}(flag_key:, default_value:, evaluation_context: nil, hooks: [], hook_hints: nil)
+              validate_default_value_type(:#{result_type}, default_value)
               evaluation_details = fetch_details(type: :#{result_type}, flag_key:, default_value:, evaluation_context:, invocation_hooks: hooks, hook_hints: hook_hints)
               #{"evaluation_details.value" if suffix == :value}
             end
@@ -72,18 +76,18 @@ module OpenFeature
       private
 
       def fetch_details(type:, flag_key:, default_value:, evaluation_context: nil, invocation_hooks: [], hook_hints: nil)
-        validate_default_value_type(type, default_value)
-
+        provider = resolve_provider
         built_context = build_evaluation_context(evaluation_context)
 
         # Assemble ordered hooks: API → Client → Invocation → Provider (spec 4.4.2)
-        provider_hooks = @provider.respond_to?(:hooks) ? Array(@provider.hooks) : []
+        provider_hooks = provider.respond_to?(:hooks) ? Array(provider.hooks) : []
         ordered_hooks = [*OpenFeature::SDK.hooks, *@hooks, *invocation_hooks, *provider_hooks]
 
-        # Short-circuit NOT_READY/FATAL providers (required by evaluation_v2.feature)
+        # Short-circuit NOT_READY/FATAL providers (required by evaluation_v2.feature). A provider resolved from the
+        # configuration is tracked while bound, so one that isn't was replaced mid-call and reads NOT_READY.
         short_circuit_code = nil
-        if OpenFeature::SDK.configuration.provider_tracked?(@provider)
-          short_circuit_code = short_circuit_error_code(provider_status)
+        if @provider ? OpenFeature::SDK.configuration.provider_tracked?(provider) : !provider.equal?(@fallback_provider)
+          short_circuit_code = short_circuit_error_code(OpenFeature::SDK.configuration.provider_state(provider))
         end
 
         # Fast path: skip hook ceremony when no hooks are registered
@@ -97,17 +101,7 @@ module OpenFeature
             return EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
           end
 
-          begin
-            return evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: built_context)
-          rescue => e
-            resolution = Provider::ResolutionDetails.new(
-              value: default_value,
-              error_code: EvaluationError.code_for(e),
-              reason: Provider::Reason::ERROR,
-              error_message: e.message
-            )
-            return EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
-          end
+          return evaluate_flag(provider: provider, type: type, flag_key: flag_key, default_value: default_value, evaluation_context: built_context)
         end
 
         hook_context = Hooks::HookContext.new(
@@ -116,7 +110,7 @@ module OpenFeature
           default_value: default_value,
           evaluation_context: built_context,
           client_metadata: @metadata,
-          provider_metadata: @provider.respond_to?(:metadata) ? @provider.metadata : nil
+          provider_metadata: provider.respond_to?(:metadata) ? provider.metadata : nil
         )
 
         hints = if hook_hints.is_a?(Hooks::Hints)
@@ -140,22 +134,31 @@ module OpenFeature
           evaluation_details
         else
           executor.execute(ordered_hooks: ordered_hooks, hook_context: hook_context, hints: hints) do |hctx|
-            evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: hctx.evaluation_context)
+            evaluate_flag(provider: provider, type: type, flag_key: flag_key, default_value: default_value, evaluation_context: hctx.evaluation_context)
           end
         end
+      rescue StandardError, NotImplementedError => e
+        # Spec 1.4.10 and 1.4.11: report through the details, never raise or log. NotImplementedError is the abstract-method idiom.
+        resolution = Provider::ResolutionDetails.new(
+          value: default_value,
+          error_code: EvaluationError.code_for(e),
+          reason: Provider::Reason::ERROR,
+          error_message: e.message
+        )
+        EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
       end
 
-      def evaluate_flag(type:, flag_key:, default_value:, evaluation_context:)
-        resolution_details = @provider.send(
+      def evaluate_flag(provider:, type:, flag_key:, default_value:, evaluation_context:)
+        resolution_details = provider.send(
           :"fetch_#{type}_value",
           flag_key: flag_key,
           default_value: default_value,
           evaluation_context: evaluation_context
         )
 
-        if TYPE_CLASS_MAP[type].none? { |klass| resolution_details.value.is_a?(klass) }
+        if resolution_details.error_code || TYPE_CLASS_MAP[type].none? { |klass| resolution_details.value.is_a?(klass) }
           resolution_details.value = default_value
-          resolution_details.error_code = Provider::ErrorCode::TYPE_MISMATCH
+          resolution_details.error_code ||= Provider::ErrorCode::TYPE_MISMATCH
           resolution_details.reason = Provider::Reason::ERROR
           resolution_details.variant = nil
         end
@@ -163,6 +166,12 @@ module OpenFeature
         EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution_details)
       end
 
+      # Callers resolve once per operation, so a rebinding mid-evaluation can't mix two providers.
+      # The fallback NoOp is never registered: untracked, so not short-circuited, and its status reads NOT_READY.
+      def resolve_provider
+        @provider || OpenFeature::SDK.configuration.provider(domain: @metadata.domain) || (@fallback_provider ||= Provider::NoOpProvider.new)
+      end
+
       def short_circuit_error_code(state)
         case state
         when ProviderState::NOT_READY then Provider::ErrorCode::PROVIDER_NOT_READY

data/lib/open_feature/sdk/configuration.rb

@@ -20,15 +20,22 @@ module OpenFeature
       attr_accessor :evaluation_context, :hooks, :transaction_context_propagator
       attr_reader :logger
 
+      # One per registration; +done+ is closed once init finishes, so waiters can pop on it
+      InitAttempt = Struct.new(:state, :error, :done, :thread)
+      private_constant :InitAttempt
+
       def initialize
         @hooks = []
         @providers = {}
+        @init_attempts = {}.compare_by_identity
+        @legacy_warned = Set.new.compare_by_identity
         @provider_mutex = Mutex.new
         @logger = nil
         @event_dispatcher = EventDispatcher.new(@logger)
         @provider_state_registry = ProviderStateRegistry.new
         @client_handlers = {}
         @client_handlers_mutex = Mutex.new
+        @dispatch_key = :"openfeature_dispatch_#{object_id}"
       end
 
       def add_hooks(*new_hooks)
@@ -55,6 +62,8 @@ module OpenFeature
 
       # @api private
       def add_client_handler(client, event_type, handler)
+        @event_dispatcher.validate_handler!(event_type, handler)
+
         @client_handlers_mutex.synchronize do
           @client_handlers[client] ||= Hash.new { |h, k| h[k] = [] }
           @client_handlers[client][event_type] << handler
@@ -118,6 +127,9 @@ module OpenFeature
         @provider_state_registry.clear
         @provider_mutex.synchronize do
           @providers.clear
+          @init_attempts.each_value { |attempt| abandon_init_attempt(attempt) }
+          @init_attempts.clear
+          @legacy_warned.clear
         end
         @hooks.clear
         @evaluation_context = nil
@@ -129,30 +141,42 @@ module OpenFeature
         context_for_init = @evaluation_context
 
         old_provider = nil
+        attempt = nil
         needs_init = false
+        init_thread = nil
         needs_shutdown = false
 
+        # Provider code runs before taking the lock: it may call back into the SDK
+        scoped = domain_scoped?(provider)
+        has_init = provider.respond_to?(:init)
+        legacy = has_init && !emits_lifecycle_events?(provider)
+        warn_legacy_provider(provider) if legacy
+
         @provider_mutex.synchronize do
-          old_provider = @providers[domain]
+          validate_domain_scoped_binding!(provider, domain, scoped)
 
-          new_providers = @providers.dup
-          new_providers[domain] = provider
-          @providers = new_providers
+          old_provider = @providers[domain]
 
-          # Spec 1.1.2.2: Only initialize if the provider is not already active
-          # (i.e., not already bound to another domain)
-          already_active = @providers.any? { |d, p| d != domain && p.equal?(provider) && @provider_state_registry.tracked?(p) }
-          needs_init = !already_active
+          # Spec 1.1.2.2: initialize once per registration; a failed init is retried on the next set
+          attempt = @init_attempts[provider]
+          needs_init = attempt.nil? || attempt.state == :failed
 
           if needs_init
+            attempt = @init_attempts[provider] = InitAttempt.new(:running, nil, Thread::Queue.new)
             @provider_state_registry.set_initial_state(provider)
             provider.send(:attach, self) if provider.is_a?(Provider::EventEmitter)
           end
 
+          # Publish last: clients read @providers without the lock, and must not see an untracked provider
+          new_providers = @providers.dup
+          new_providers[domain] = provider
+          @providers = new_providers
+
           # Spec 1.1.2.3: Only shutdown old provider if it's no longer bound to any domain
           if old_provider && !old_provider.equal?(provider)
             needs_shutdown = !provider_bound?(old_provider)
             if needs_shutdown
+              abandon_init_attempt(@init_attempts.delete(old_provider))
               @provider_state_registry.remove_provider(old_provider)
               old_provider.send(:detach) if old_provider.is_a?(Provider::EventEmitter)
             end
@@ -170,67 +194,139 @@ module OpenFeature
 
         # Initialize provider outside the mutex to avoid blocking other operations
         if needs_init
-          if wait_for_init
-            init_provider(provider, context_for_init, raise_on_error: true)
+          # Spec 2.8.5.1: a provider without init is READY, and its handlers have run, when set_provider returns
+          if wait_for_init || !has_init
+            init_provider(provider, context_for_init, domain:, attempt:, raise_on_error: wait_for_init)
+            # Replaced or shut down while init ran: fail like the waiters on this attempt did
+            raise incomplete_init_error(provider, "initialization did not complete") if wait_for_init && attempt.state != :succeeded
           else
-            Thread.new do
-              init_provider(provider, context_for_init, raise_on_error: false)
+            init_thread = Thread.new do
+              init_provider(provider, context_for_init, domain:, attempt:, raise_on_error: false)
             end
           end
+        elsif !has_init
+          # Spec 2.8.5.1: each new binding of a provider without init runs its domain's READY handlers
+          dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY, token: attempt) unless old_provider.equal?(provider)
         elsif wait_for_init
-          # Provider already active; no init needed but still dispatch READY
-          dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY)
+          # Already registered: wait for an init still in flight, then report its outcome.
+          # From inside that init (e.g. a handler of an event it emits) the wait could never end.
+          raise incomplete_init_error(provider, "is still initializing on this thread") if running_on_this_thread?(attempt)
+
+          attempt.done.pop
+          raise attempt.error || incomplete_init_error(provider, "initialization did not complete") unless attempt.state == :succeeded
+
+          dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY, token: attempt) if legacy
         end
+      ensure
+        # Fail an attempt no init took over (e.g. a Timeout hit first), or it would stay running forever
+        finish_init_attempt(attempt, :failed) if needs_init && !init_thread
       end
 
-      def init_provider(provider, context, raise_on_error: false)
-        if provider.respond_to?(:init)
-          init_method = provider.method(:init)
-          if init_method.parameters.empty?
-            provider.init
-          else
-            provider.init(context)
-          end
-        end
+      def init_provider(provider, context, domain:, attempt:, raise_on_error: false)
+        emits_lifecycle_events = emits_lifecycle_events?(provider)
+        attempt.thread = Thread.current
+        call_init(provider, context, domain)
 
-        dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY)
+        # Settle the attempt before handlers run, so a handler can register this provider again.
+        # An abandoned attempt (provider replaced or shut down meanwhile) reports no READY.
+        # Spec 2.8.2/2.8.3: a provider that emits its own lifecycle events gets no synthetic READY or ERROR
+        dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY, token: attempt) if finish_init_attempt(attempt, :succeeded) && !emits_lifecycle_events
       rescue => e
         # Spec 1.7.5: PROVIDER_FATAL from init makes the provider FATAL
         error_code = EvaluationError.code_for(e)
-
-        dispatch_provider_event(provider, ProviderEvent::PROVIDER_ERROR,
+        error = ProviderInitializationError.new(
+          "Provider #{provider.class.name} initialization failed: #{e.message}",
+          provider:,
           error_code: error_code,
-          message: e.message)
-
-        if raise_on_error
-          raise ProviderInitializationError.new(
-            "Provider #{provider.class.name} initialization failed: #{e.message}",
-            provider:,
-            error_code: error_code,
-            original_error: e
-          )
+          original_error: e
+        )
+        finish_init_attempt(attempt, :failed, error)
+
+        unless emits_lifecycle_events
+          dispatch_provider_event(provider, ProviderEvent::PROVIDER_ERROR,
+            {error_code: error_code, message: e.message}, token: attempt)
         end
+
+        raise error if raise_on_error
+      ensure
+        # Reached unsettled only when init raised something other than a StandardError
+        finish_init_attempt(attempt, :failed)
+      end
+
+      # Caller holds @provider_mutex: the provider was unbound or the API reset before its init settled
+      def abandon_init_attempt(attempt)
+        return unless attempt
+
+        attempt.state = :failed if attempt.state == :running
+        attempt.done.close
       end
 
-      def dispatch_provider_event(provider, event_type, details = {})
-        # Under the replacement lock, so a late event can't re-track a replaced or shut-down provider
+      def incomplete_init_error(provider, reason)
+        ProviderInitializationError.new("Provider #{provider.class.name} #{reason}", provider:, error_code: Provider::ErrorCode::GENERAL)
+      end
+
+      def finish_init_attempt(attempt, state, error = nil)
         @provider_mutex.synchronize do
-          return unless provider_bound?(provider)
+          return false unless attempt.state == :running
 
-          @provider_state_registry.update_state_from_event(provider, event_type, details)
+          attempt.state = state
+          attempt.error = error
         end
+        attempt.done.close
+        true
+      end
 
-        provider_name = extract_provider_name(provider)
+      # An event for a provider already dispatching on this call stack is queued behind the current one
+      def dispatch_provider_event(provider, event_type, details = {}, token: nil)
+        # Lifecycle events (the SDK's own, or the provider's from its init thread) record status when sent, so
+        # set_provider_and_wait returns with it even from the provider's own handler (1.1.2.4); others record it when delivered (5.3.5)
+        token ||= running_init_attempt_on_this_thread(provider)
+        return if token && !accept_provider_event(provider, event_type, details, token)
+
+        queues = (Thread.current[@dispatch_key] ||= {}.compare_by_identity)
+        if (queue = queues[provider])
+          queue << [event_type, details.dup, token]
+          return
+        end
 
-        event_details = {
-          provider_name: provider_name
-        }.merge(details)
+        queue = queues[provider] = [[event_type, details, token]]
+        begin
+          deliver_provider_event(provider, *queue.shift)
+          until queue.empty?
+            begin
+              deliver_provider_event(provider, *queue.shift)
+            rescue => e
+              # Its own emitter already returned, so log rather than fail the event that was dispatching
+              @logger&.error("Queued provider event failed: #{e.message}")
+            end
+          end
+        ensure
+          queues.delete(provider)
+          Thread.current[@dispatch_key] = nil if queues.empty?
+        end
+      end
 
+      def deliver_provider_event(provider, event_type, details, token)
+        return unless accept_provider_event(provider, event_type, details, token, record_status: token.nil?)
+
+        event_details = {provider_name: extract_provider_name(provider)}.merge(details)
         run_handlers_for_provider(provider, event_type, event_details)
       end
 
       private
 
+      # Under the replacement lock, so a late event can't re-track a replaced or shut-down provider
+      def accept_provider_event(provider, event_type, details, token, record_status: true)
+        @provider_mutex.synchronize do
+          return false unless provider_bound?(provider)
+          # An SDK READY/ERROR from an earlier registration of this provider is stale
+          return false unless token.nil? || @init_attempts[provider].equal?(token)
+
+          @provider_state_registry.update_state_from_event(provider, event_type, details) if record_status
+          true
+        end
+      end
+
       def provider_bound?(provider)
         @providers.each_value.any? { |p| p.equal?(provider) }
       end
@@ -239,26 +335,78 @@ module OpenFeature
         provider.respond_to?(:metadata) ? provider.metadata.name : provider.class.name
       end
 
+      def domain_scoped?(provider)
+        provider.respond_to?(:domain_scoped?) && provider.domain_scoped?
+      end
+
+      # Spec 2.8.5.1: without init there's nothing to report, so the marker only counts alongside init
+      def emits_lifecycle_events?(provider)
+        provider.respond_to?(:init) && provider.respond_to?(:emits_lifecycle_events?) && provider.emits_lifecycle_events?
+      end
+
+      def running_init_attempt_on_this_thread(provider)
+        attempt = @provider_mutex.synchronize { @init_attempts[provider] }
+        attempt if attempt && running_on_this_thread?(attempt)
+      end
+
+      def running_on_this_thread?(attempt)
+        attempt.state == :running && attempt.thread.equal?(Thread.current)
+      end
+
+      def warn_legacy_provider(provider)
+        return if @logger.nil? || !@provider_mutex.synchronize { @legacy_warned.add?(provider.class) }
+        @logger.warn("Provider #{extract_provider_name(provider)} relies on SDK-emitted lifecycle events, which are deprecated; " \
+          "emit PROVIDER_READY/PROVIDER_ERROR from init and define emits_lifecycle_events? returning true (spec Appendix E)")
+      end
+
+      def validate_domain_scoped_binding!(provider, domain, scoped)
+        return unless scoped && provider_bound?(provider) && !@providers[domain].equal?(provider)
+
+        raise ArgumentError, "Cannot bind domain-scoped provider to more than one domain"
+      end
+
+      def call_init(provider, context, domain)
+        return unless provider.respond_to?(:init)
+
+        parameters = provider.method(:init).parameters
+        takes_domain = init_accepts_domain?(parameters)
+        if !takes_domain && domain_scoped?(provider)
+          @logger&.warn("Provider #{extract_provider_name(provider)} is domain-scoped but its init doesn't accept domain:")
+        end
+
+        args = init_accepts_evaluation_context?(parameters) ? [context] : []
+        provider.init(*args, **(takes_domain ? {domain:} : {}))
+      end
+
+      # Anonymous `**` (from `...`) and delegators' bare `*` can't be trusted to accept `domain:`
+      def init_accepts_domain?(parameters)
+        parameters.any? do |kind, name|
+          ((kind == :key || kind == :keyreq) && name == :domain) || (kind == :keyrest && name && name != :**)
+        end
+      end
+
+      def init_accepts_evaluation_context?(parameters)
+        parameters.any? { |kind, _| kind == :req || kind == :opt || kind == :rest }
+      end
+
       def run_handlers_for_provider(provider, event_type, event_details)
         # Run global handlers (API-level, no domain filtering)
         @event_dispatcher.trigger_event(event_type, event_details)
 
-        # Run client handlers (domain-scoped)
-        @client_handlers_mutex.synchronize do
-          @client_handlers.each do |client, handlers_by_event|
+        # Run client handlers (domain-scoped) outside the lock, so they can add or remove handlers
+        handlers = @client_handlers_mutex.synchronize do
+          @client_handlers.flat_map do |client, handlers_by_event|
             # Check if this client should receive events from this provider
             client_provider = provider(domain: client.metadata.domain)
-            next unless client_provider&.equal?(provider)
-
-            # Trigger handlers for this client
-            handlers = handlers_by_event[event_type]
-            handlers.each do |handler|
-              handler.call(event_details)
-            rescue => e
-              @logger&.error("Client event handler failed: #{e.message}")
-            end
+            client_provider&.equal?(provider) ? handlers_by_event[event_type] : []
           end
         end
+
+        handlers.each do |handler|
+          handler.call(event_details)
+        rescue => e
+          @logger&.error("Client event handler failed: #{e.message}")
+        end
       end
 
       def run_immediate_handler(event_type, handler, client)
@@ -270,8 +418,8 @@ module OpenFeature
         }
 
         if client.nil?
-          # API-level handler: check all providers
-          @providers.each do |domain, provider|
+          # API-level handler: check each bound provider once, however many domains it's bound to
+          @providers.values.uniq(&:object_id).each do |provider|
             next unless provider
 
             provider_state = @provider_state_registry.get_state(provider)

data/lib/open_feature/sdk/event_dispatcher.rb

@@ -16,14 +16,18 @@ module OpenFeature
       end
 
       def add_handler(event_type, handler)
-        raise ArgumentError, "Invalid event type: #{event_type}" unless valid_event?(event_type)
-        raise ArgumentError, "Handler must respond to call" unless handler.respond_to?(:call)
+        validate_handler!(event_type, handler)
 
         @mutex.synchronize do
           @handlers[event_type] << handler
         end
       end
 
+      def validate_handler!(event_type, handler)
+        raise ArgumentError, "Invalid event type: #{event_type}" unless valid_event?(event_type)
+        raise ArgumentError, "Handler must respond to call" unless handler.respond_to?(:call)
+      end
+
       def remove_handler(event_type, handler)
         return unless valid_event?(event_type)
 

data/lib/open_feature/sdk/hooks/hook_executor.rb

@@ -54,7 +54,7 @@ module OpenFeature
             else
               run_after_hooks(ordered_hooks, hook_context, evaluation_details, hints)
             end
-          rescue => e
+          rescue StandardError, NotImplementedError => e
             run_error_hooks(ordered_hooks, hook_context, e, hints)
 
             evaluation_details = EvaluationDetails.new(

data/lib/open_feature/sdk/provider/in_memory_provider.rb

@@ -19,10 +19,6 @@ module OpenFeature
           @flags = flags
         end
 
-        def init(evaluation_context = nil)
-          # Intentional no-op, used for testing
-        end
-
         def shutdown
           # Intentional no-op, used for testing
         end

data/lib/open_feature/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module OpenFeature
   module SDK
-    VERSION = "0.6.6"
+    VERSION = "0.7.0"
   end
 end

data/sig/open_feature/sdk/client.rbs

@@ -7,10 +7,10 @@ module OpenFeature
       EMPTY_HINTS: Hooks::Hints
 
       attr_reader metadata: ClientMetadata
-      attr_reader evaluation_context: EvaluationContext?
+      attr_accessor evaluation_context: EvaluationContext?
       attr_accessor hooks: Array[untyped]
 
-      def initialize: (provider: untyped, ?domain: String?, ?evaluation_context: EvaluationContext?) -> void
+      def initialize: (?provider: untyped, ?domain: String?, ?evaluation_context: EvaluationContext?) -> void
 
       def add_hooks: (*Array[untyped] new_hooks) -> void
 
@@ -40,7 +40,8 @@ module OpenFeature
       private
 
       def fetch_details: (type: Symbol, flag_key: String, default_value: untyped, ?evaluation_context: EvaluationContext?, ?invocation_hooks: Array[untyped], ?hook_hints: Hooks::Hints?) -> EvaluationDetails?
-      def evaluate_flag: (type: Symbol, flag_key: String, default_value: untyped, evaluation_context: EvaluationContext?) -> EvaluationDetails
+      def evaluate_flag: (provider: untyped, type: Symbol, flag_key: String, default_value: untyped, evaluation_context: EvaluationContext?) -> EvaluationDetails
+      def resolve_provider: () -> untyped
       def short_circuit_error_code: (String state) -> String?
       def build_evaluation_context: (EvaluationContext? invocation_context) -> EvaluationContext?
       def validate_default_value_type: (Symbol type, untyped default_value) -> void

data/sig/open_feature/sdk/configuration.rbs

@@ -32,9 +32,23 @@ module OpenFeature
 
       def reset: () -> void
       def set_provider_internal: (untyped provider, domain: String?, wait_for_init: bool) -> void
-      def init_provider: (untyped provider, EvaluationContext? context, ?raise_on_error: bool) -> void
-      def dispatch_provider_event: (untyped provider, String event_type, ?Hash[Symbol, untyped] details) -> void
+      def init_provider: (untyped provider, EvaluationContext? context, domain: String?, attempt: untyped, ?raise_on_error: bool) -> void
+      def finish_init_attempt: (untyped attempt, Symbol state, ?ProviderInitializationError? error) -> bool
+      def abandon_init_attempt: (untyped attempt) -> void
+      def incomplete_init_error: (untyped provider, String reason) -> ProviderInitializationError
+      def dispatch_provider_event: (untyped provider, String event_type, ?Hash[Symbol, untyped] details, ?token: untyped) -> void
+      def deliver_provider_event: (untyped provider, String event_type, Hash[Symbol, untyped]? details, untyped token) -> void
+      def accept_provider_event: (untyped provider, String event_type, Hash[Symbol, untyped]? details, untyped token, ?record_status: bool) -> bool
       def provider_bound?: (untyped provider) -> bool
+      def domain_scoped?: (untyped provider) -> bool
+      def emits_lifecycle_events?: (untyped provider) -> bool
+      def warn_legacy_provider: (untyped provider) -> void
+      def running_init_attempt_on_this_thread: (untyped provider) -> untyped
+      def running_on_this_thread?: (untyped attempt) -> bool
+      def validate_domain_scoped_binding!: (untyped provider, String? domain, bool scoped) -> void
+      def call_init: (untyped provider, EvaluationContext? context, String? domain) -> void
+      def init_accepts_domain?: (Array[[Symbol, Symbol?]] parameters) -> bool
+      def init_accepts_evaluation_context?: (Array[[Symbol, Symbol?]] parameters) -> bool
       def extract_provider_name: (untyped provider) -> String
       def run_handlers_for_provider: (untyped provider, String event_type, Hash[Symbol, untyped] event_details) -> void
       def run_immediate_handler: (String event_type, _ToProc handler, Client? client) -> void

data/sig/open_feature/sdk/event_dispatcher.rbs

@@ -6,6 +6,7 @@ module OpenFeature
       def initialize: (?untyped? logger) -> void
 
       def add_handler: (String event_type, _ToProc handler) -> void
+      def validate_handler!: (String event_type, untyped handler) -> void
       def remove_handler: (String event_type, _ToProc handler) -> void
       def remove_all_handlers: (String event_type) -> void
       def trigger_event: (String event_type, ?Hash[Symbol, untyped] event_details) -> void

data/sig/open_feature/sdk/provider/in_memory_provider.rbs

@@ -20,7 +20,6 @@ module OpenFeature
 
         def initialize: (?Hash[String, untyped] flags) -> void
 
-        def init: (?EvaluationContext? evaluation_context) -> void
         def shutdown: () -> void
 
         def add_flag: (flag_key: String, value: untyped) -> void

data/sig/open_feature/sdk/provider.rbs

@@ -11,11 +11,15 @@ module OpenFeature
       end
 
       interface _LifecycleProvider
-        def init: (?EvaluationContext? evaluation_context) -> void
+        def init: (?EvaluationContext? evaluation_context, ?domain: String?) -> void
         def shutdown: () -> void
         def metadata: () -> ProviderMetadata
       end
 
+      interface _DomainScopedProvider
+        def domain_scoped?: () -> bool
+      end
+
       interface _TrackableProvider
         def track: (String tracking_event_name, ?evaluation_context: EvaluationContext?, ?tracking_event_details: TrackingEventDetails?) -> void
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openfeature-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.6
+  version: 0.7.0
 platform: ruby
 authors:
 - OpenFeature Authors