openfeature-sdk 0.6.7 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93f85fdb9eb64b634a3267d0987415f3e4b9033a9d864e80478dfde83074fa7d
-  data.tar.gz: 14e94971fdae29a56d31db9d8ee44716b805b6783e0d381ac04e6348168ccf67
+  metadata.gz: 1b8b6e8a5fd01205278fa44c809eb3c1ef578b56e5542aa94793a090e605458d
+  data.tar.gz: f85c7d0e8b804fb651e02cc3c59d14c21458f9fdb419d58df6d8fbb714a35b9b
 SHA512:
-  metadata.gz: c1e726bae4617d91ed82f676270bb51b7355e8694fac68a76af5f8ea046ed60c33d4c31b0a716827ad61edffe2849c3eb444c614975ac8a09707dcf620286c03
-  data.tar.gz: 47d740d86cac2c493058c0f35aa6c2489d89f0502e8df3eb9ba850585777934478fe2dcf500b7eac9b71c96cfb2c857bc6026e9d1214e7876bc385788fcf6f18
+  metadata.gz: a7fef199498fb02863ed74cf76a6fbff8acf65df23e2e5d4baad90b6ed3da589b6ca98da1540443a7367456a527819eb2380979aa4f1a1ef8780c33ccf425d32
+  data.tar.gz: 71db2db0d85592861ebd5f117d7599e9d54374deb9a6eae5060716044abddb27a4bd10db7ca07314540a36adeb7c366afa1a8c21fb4f19824e05e15fd59a1a27

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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)
 
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openfeature-sdk (0.6.7)
+    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.7">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.7&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,7 +301,11 @@ 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.
+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`.
 
@@ -314,15 +319,17 @@ 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
@@ -446,13 +453,23 @@ You’ll then need to write the provider by implementing the `Provider` duck.
 
 ```ruby
 class MyProvider
+  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
+    # 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.

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,12 +51,13 @@ 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)
-      rescue
+        provider.track(tracking_event_name, evaluation_context: built_context, tracking_event_details: tracking_event_details)
+      rescue StandardError, NotImplementedError
         nil
       end
 
@@ -75,16 +76,18 @@ module OpenFeature
       private
 
       def fetch_details(type:, flag_key:, default_value:, evaluation_context: nil, invocation_hooks: [], hook_hints: nil)
+        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
@@ -98,7 +101,7 @@ module OpenFeature
             return EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
           end
 
-          return evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: built_context)
+          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(
@@ -107,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)
@@ -131,7 +134,7 @@ 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
@@ -145,8 +148,8 @@ module OpenFeature
         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,
@@ -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

@@ -21,19 +21,21 @@ module OpenFeature
       attr_reader :logger
 
       # One per registration; +done+ is closed once init finishes, so waiters can pop on it
-      InitAttempt = Struct.new(:state, :error, :done)
+      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)
@@ -60,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
@@ -123,9 +127,9 @@ module OpenFeature
         @provider_state_registry.clear
         @provider_mutex.synchronize do
           @providers.clear
-          # Release anyone waiting on an init that shutdown cut short
-          @init_attempts.each_value { |attempt| attempt.done.close }
+          @init_attempts.each_value { |attempt| abandon_init_attempt(attempt) }
           @init_attempts.clear
+          @legacy_warned.clear
         end
         @hooks.clear
         @evaluation_context = nil
@@ -144,16 +148,15 @@ module OpenFeature
 
         # 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
           validate_domain_scoped_binding!(provider, domain, scoped)
 
           old_provider = @providers[domain]
 
-          new_providers = @providers.dup
-          new_providers[domain] = provider
-          @providers = new_providers
-
           # 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
@@ -164,11 +167,16 @@ module OpenFeature
             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
-              @init_attempts.delete(old_provider)
+              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
@@ -186,25 +194,28 @@ 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, domain:, attempt:, 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
             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
-          # Already registered: wait for an init still in flight, then report its outcome
+          # 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
-          unless attempt.state == :succeeded
-            raise attempt.error || ProviderInitializationError.new(
-              "Provider #{provider.class.name} initialization did not complete",
-              provider:,
-              error_code: Provider::ErrorCode::GENERAL
-            )
-          end
+          raise attempt.error || incomplete_init_error(provider, "initialization did not complete") unless attempt.state == :succeeded
 
-          dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY)
+          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
@@ -212,11 +223,14 @@ module OpenFeature
       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)
 
-        # Settle the attempt before handlers run, so a handler can register this provider again
-        finish_init_attempt(attempt, :succeeded)
-        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)
@@ -228,9 +242,10 @@ module OpenFeature
         )
         finish_init_attempt(attempt, :failed, error)
 
-        dispatch_provider_event(provider, ProviderEvent::PROVIDER_ERROR,
-          error_code: error_code,
-          message: e.message)
+        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
@@ -238,35 +253,80 @@ module OpenFeature
         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 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 attempt.state == :running
+          return false unless attempt.state == :running
 
           attempt.state = state
           attempt.error = error
         end
         attempt.done.close
+        true
       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
-        @provider_mutex.synchronize do
-          return unless provider_bound?(provider)
-
-          @provider_state_registry.update_state_from_event(provider, event_type, details)
+      # 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
 
-        provider_name = extract_provider_name(provider)
+        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
 
-        event_details = {
-          provider_name: provider_name
-        }.merge(details)
+      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
@@ -279,6 +339,26 @@ module OpenFeature
         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)
 
@@ -313,22 +393,20 @@ module OpenFeature
         # 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)
@@ -340,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.7"
+    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

@@ -33,10 +33,18 @@ 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, domain: String?, attempt: untyped, ?raise_on_error: bool) -> void
-      def finish_init_attempt: (untyped attempt, Symbol state, ?ProviderInitializationError? error) -> void
-      def dispatch_provider_event: (untyped provider, String event_type, ?Hash[Symbol, untyped] details) -> 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

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

metadata

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