openfeature-sdk 0.6.7 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93f85fdb9eb64b634a3267d0987415f3e4b9033a9d864e80478dfde83074fa7d
-  data.tar.gz: 14e94971fdae29a56d31db9d8ee44716b805b6783e0d381ac04e6348168ccf67
+  metadata.gz: bf1041c34e962f832b25f1be3e9eeab7fee3fd4272dc9e1e0e8dabe85b6d21e8
+  data.tar.gz: f45667a6a898d3521ea87c31aea62491ace0682c72ef2cfa2a16d5f8a0f3f0b5
 SHA512:
-  metadata.gz: c1e726bae4617d91ed82f676270bb51b7355e8694fac68a76af5f8ea046ed60c33d4c31b0a716827ad61edffe2849c3eb444c614975ac8a09707dcf620286c03
-  data.tar.gz: 47d740d86cac2c493058c0f35aa6c2489d89f0502e8df3eb9ba850585777934478fe2dcf500b7eac9b71c96cfb2c857bc6026e9d1214e7876bc385788fcf6f18
+  metadata.gz: 393adb8b637763e5b397f6ee702017705bf355c8785ceb1280aa4f95b585a061f8da6e4a6d67ed9e8ab20de1f341b36d4dc3febb38dbbcc7a41a68cfb8002b8c
+  data.tar.gz: d145cc98fb609aa75ad06485d4486cc6aec19ea953cd627f9f71b33e991fafd3a57fa139fbe07f878e5bc105885ce35a74c0ab12485e50649d63b79a100eec98

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.7.1](https://github.com/open-feature/ruby-sdk/compare/v0.7.0...v0.7.1) (2026-10-23)
+
+
+### Features
+
+* isolated API instances ([#354](https://github.com/open-feature/ruby-sdk/issues/354)) ([1c92b4a](https://github.com/open-feature/ruby-sdk/commit/1c92b4ad7550a6b345e7471f84cd5a7ff445591e))
+
+
+### Bug Fixes
+
+* key provider state by identity, default the NoOp reason, freeze client metadata ([#355](https://github.com/open-feature/ruby-sdk/issues/355)) ([d15bd84](https://github.com/open-feature/ruby-sdk/commit/d15bd84e1456b6200e29c12c3463c4f8ddfe693f))
+
+## [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.1)
 
 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.1">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.7.1&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
@@ -436,6 +443,29 @@ class MyRequestScopedPropagator
 end
 ```
 
+### Isolated API instances
+
+`OpenFeature::SDK` is a global singleton. Some applications need more than one independent API in a process, for example separately developed modules that each need their own provider, or tests that run in parallel. Require the factory explicitly to create one:
+
+```ruby
+require "open_feature/sdk/isolated"
+
+api = OpenFeature::SDK::Isolated.create_api
+api.set_provider_and_wait(MyProvider.new)
+client = api.build_client
+client.fetch_boolean_value(flag_key: "my-flag", default_value: false)
+```
+
+Each instance has its own providers, hooks, evaluation context, event handlers, transaction context propagator and `shutdown`, and shares none of them with `OpenFeature::SDK` or other instances.
+Build its clients with `api.build_client`; `OpenFeature::SDK::Client.new` binds to the global API.
+Prefer the global API unless you need this.
+
+A provider instance should be registered with only one API at a time.
+Registering a provider that includes `OpenFeature::SDK::Provider::EventEmitter` with a second API raises `ArgumentError`; other providers can't be detected.
+Once the first API replaces the provider or shuts down, it can be registered with another.
+
+A `LoggingHook` created without `logger:` logs to the global API's logger, even when added to an isolated API. Pass `logger:` to use another.
+
 ## Extending
 
 ### Develop a provider
@@ -446,13 +476,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

@@ -32,13 +32,15 @@ module OpenFeature
     #
     #   client = OpenFeature::SDK::API.instance.build_client(name: 'my-open-feature-client')
     class API
-      include Singleton # Satisfies Flag Evaluation API Requirement 1.1.1
+      include Singleton # Satisfies Flag Evaluation API Requirement 1.1.1; Isolated.create_api builds others (1.8.1)
       extend Forwardable
 
       def_delegators :configuration, :provider, :set_provider, :set_provider_and_wait, :hooks, :add_hooks, :evaluation_context
 
-      def configuration
-        @configuration ||= Configuration.new
+      attr_reader :configuration
+
+      def initialize
+        @configuration = Configuration.new
       end
 
       def configure(&block)
@@ -48,11 +50,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:, configuration:)
       end
 
       def provider_metadata(domain: nil)

data/lib/open_feature/sdk/client.rb

@@ -17,12 +17,13 @@ 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, configuration: API.instance.configuration)
         @provider = provider
+        @configuration = configuration
         @metadata = ClientMetadata.new(domain:)
         @evaluation_context = evaluation_context
         @hooks = []
@@ -33,17 +34,17 @@ module OpenFeature
       end
 
       def provider_status
-        OpenFeature::SDK.configuration.provider_state(@provider)
+        @configuration.provider_state(resolve_provider)
       end
 
       def add_handler(event_type, handler = nil, &block)
         actual_handler = handler || block
-        OpenFeature::SDK.configuration.add_client_handler(self, event_type, actual_handler)
+        @configuration.add_client_handler(self, event_type, actual_handler)
       end
 
       def remove_handler(event_type, handler = nil, &block)
         actual_handler = handler || block
-        OpenFeature::SDK.configuration.remove_client_handler(self, event_type, actual_handler)
+        @configuration.remove_client_handler(self, event_type, actual_handler)
       end
 
       # Tracking API (spec 6.1.1.1) — dynamic-context paradigm
@@ -51,12 +52,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 +77,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) : []
-        ordered_hooks = [*OpenFeature::SDK.hooks, *@hooks, *invocation_hooks, *provider_hooks]
+        provider_hooks = provider.respond_to?(:hooks) ? Array(provider.hooks) : []
+        ordered_hooks = [*@configuration.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 ? @configuration.provider_tracked?(provider) : !provider.equal?(@fallback_provider)
+          short_circuit_code = short_circuit_error_code(@configuration.provider_state(provider))
         end
 
         # Fast path: skip hook ceremony when no hooks are registered
@@ -98,7 +102,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 +111,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)
@@ -118,7 +122,7 @@ module OpenFeature
           EMPTY_HINTS
         end
 
-        executor = Hooks::HookExecutor.new(logger: OpenFeature::SDK.configuration.logger)
+        executor = Hooks::HookExecutor.new(logger: @configuration.logger)
 
         if short_circuit_code
           resolution = Provider::ResolutionDetails.new(
@@ -131,7 +135,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 +149,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 +167,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 || @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
@@ -171,11 +181,11 @@ module OpenFeature
       end
 
       def build_evaluation_context(invocation_context)
-        propagator = OpenFeature::SDK.configuration.transaction_context_propagator
+        propagator = @configuration.transaction_context_propagator
         transaction_context = propagator&.get_transaction_context
 
         EvaluationContextBuilder.new.call(
-          api_context: OpenFeature::SDK.evaluation_context,
+          api_context: @configuration.evaluation_context,
           transaction_context: transaction_context,
           client_context: evaluation_context,
           invocation_context: invocation_context

data/lib/open_feature/sdk/client_metadata.rb

@@ -4,6 +4,11 @@ module OpenFeature
   module SDK
     ClientMetadata = Struct.new(:domain, keyword_init: true) do
       alias_method :name, :domain
+
+      def initialize(domain: nil)
+        super(domain: domain&.dup&.freeze)
+        freeze
+      end
     end
   end
 end

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,31 +148,36 @@ 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
 
           if needs_init
+            # First, so a provider registered with another API (1.8.4) leaves no state behind
+            provider.send(:attach, self) if provider.is_a?(Provider::EventEmitter)
             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
-              @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,37 +195,43 @@ 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
-        finish_init_attempt(attempt, :failed) if needs_init && !init_thread
+        finish_init_attempt(attempt, :failed) if needs_init && attempt && !init_thread
       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 +243,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 +254,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 +340,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 +394,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 +419,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/isolated.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "../sdk"
+
+module OpenFeature
+  module SDK
+    # Spec 1.8.3: a separate require, so isolated instances are an explicit opt-in
+    module Isolated
+      # Spec 1.8.1: a new API that shares no state with the global one or other isolated APIs
+      def self.create_api
+        API.send(:new)
+      end
+    end
+  end
+end

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

@@ -8,7 +8,7 @@ module OpenFeature
       # Mixin for providers that emit lifecycle events
       module EventEmitter
         def emit_event(event_type, details = {})
-          config = @configuration
+          config = @openfeature_configuration
           return unless config
 
           unless ::OpenFeature::SDK::ProviderEvent::ALL_EVENTS.include?(event_type)
@@ -19,17 +19,22 @@ module OpenFeature
         end
 
         def configuration_attached?
-          !@configuration.nil?
+          !@openfeature_configuration.nil?
         end
 
         private
 
         def attach(configuration)
-          @configuration = configuration
+          # Spec 1.8.4: only providers using this mixin know which API they're registered with
+          if @openfeature_configuration && !@openfeature_configuration.equal?(configuration)
+            raise ArgumentError, "Provider is already registered with another OpenFeature API instance"
+          end
+
+          @openfeature_configuration = configuration
         end
 
         def detach
-          @configuration = nil
+          @openfeature_configuration = nil
         end
       end
     end

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/provider/no_op_provider.rb

@@ -23,7 +23,7 @@ module OpenFeature
       # * <tt>fetch_object_value</tt> - Retrieve feature flag object value
       #
       class NoOpProvider
-        REASON_NO_OP = "No-op"
+        REASON_NO_OP = Reason::DEFAULT
         NAME = "No-op Provider"
 
         attr_reader :metadata

data/lib/open_feature/sdk/provider_initialization_error.rb

@@ -21,8 +21,8 @@ module OpenFeature
       # @param message [String] the error message
       # @param provider [Object] the provider that failed to initialize
       # @param original_error [Exception] the original error that caused the failure
-      # @param error_code [String] the OpenFeature error code (defaults to PROVIDER_FATAL)
-      def initialize(message, provider: nil, original_error: nil, error_code: Provider::ErrorCode::PROVIDER_FATAL)
+      # @param error_code [String] the OpenFeature error code (defaults to GENERAL)
+      def initialize(message, provider: nil, original_error: nil, error_code: Provider::ErrorCode::GENERAL)
         super(message)
         @provider = provider
         @original_error = original_error

data/lib/open_feature/sdk/provider_state_registry.rb

@@ -9,7 +9,7 @@ module OpenFeature
     # Tracks provider states
     class ProviderStateRegistry
       def initialize
-        @states = {}
+        @states = {}.compare_by_identity
         @mutex = Mutex.new
       end
 
@@ -17,7 +17,7 @@ module OpenFeature
         return unless provider
 
         @mutex.synchronize do
-          @states[provider.object_id] = {state: state, details: {}}
+          @states[provider] = {state: state, details: {}}
         end
       end
 
@@ -29,7 +29,7 @@ module OpenFeature
         # Only update state if the event should cause a state change
         if new_state
           @mutex.synchronize do
-            @states[provider.object_id] = {state: new_state, details: event_details || {}}
+            @states[provider] = {state: new_state, details: event_details || {}}
           end
           new_state
         else
@@ -42,7 +42,7 @@ module OpenFeature
         return ProviderState::NOT_READY unless provider
 
         @mutex.synchronize do
-          entry = @states[provider.object_id]
+          entry = @states[provider]
           entry ? entry[:state] : ProviderState::NOT_READY
         end
       end
@@ -51,7 +51,7 @@ module OpenFeature
         return {} unless provider
 
         @mutex.synchronize do
-          entry = @states[provider.object_id]
+          entry = @states[provider]
           entry ? entry[:details] : {}
         end
       end
@@ -60,7 +60,7 @@ module OpenFeature
         return unless provider
 
         @mutex.synchronize do
-          @states.delete(provider.object_id)
+          @states.delete(provider)
         end
       end
 
@@ -68,7 +68,7 @@ module OpenFeature
         return false unless provider
 
         @mutex.synchronize do
-          @states.key?(provider.object_id)
+          @states.key?(provider)
         end
       end
 

data/lib/open_feature/sdk/thread_local_transaction_context_propagator.rb

@@ -5,14 +5,19 @@ module OpenFeature
     class ThreadLocalTransactionContextPropagator
       include TransactionContextPropagator
 
+      # One context per propagator under this key, so separate APIs never share one (spec 1.8.2)
+      # while resetting the key still clears them all. Weak keys let discarded propagators be collected.
       THREAD_KEY = :openfeature_transaction_context
 
       def set_transaction_context(evaluation_context)
-        Thread.current[THREAD_KEY] = evaluation_context
+        contexts = Thread.current[THREAD_KEY]
+        contexts = Thread.current[THREAD_KEY] = ObjectSpace::WeakKeyMap.new unless contexts.is_a?(ObjectSpace::WeakKeyMap)
+        evaluation_context.nil? ? contexts.delete(self) : contexts[self] = evaluation_context
       end
 
       def get_transaction_context
-        Thread.current[THREAD_KEY]
+        contexts = Thread.current[THREAD_KEY]
+        contexts[self] if contexts.is_a?(ObjectSpace::WeakKeyMap)
       end
     end
   end

data/lib/open_feature/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module OpenFeature
   module SDK
-    VERSION = "0.6.7"
+    VERSION = "0.7.1"
   end
 end

data/sig/open_feature/sdk/api.rbs

@@ -1,10 +1,13 @@
 module OpenFeature
   module SDK
     class API
-      include Singleton
       extend Forwardable
 
-      def configuration: () -> Configuration
+      include Singleton
+
+      attr_reader configuration: Configuration
+
+      def initialize: () -> void
 
       def configure: () { (Configuration) -> void } -> void
 

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?, ?configuration: Configuration) -> 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/isolated.rbs

@@ -0,0 +1,7 @@
+module OpenFeature
+  module SDK
+    module Isolated
+      def self.create_api: () -> API
+    end
+  end
+end

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.1
 platform: ruby
 authors:
 - OpenFeature Authors
@@ -55,6 +55,7 @@ files:
 - lib/open_feature/sdk/hooks/hook_context.rb
 - lib/open_feature/sdk/hooks/hook_executor.rb
 - lib/open_feature/sdk/hooks/logging_hook.rb
+- lib/open_feature/sdk/isolated.rb
 - lib/open_feature/sdk/provider.rb
 - lib/open_feature/sdk/provider/error_code.rb
 - lib/open_feature/sdk/provider/event_emitter.rb
@@ -92,6 +93,7 @@ files:
 - sig/open_feature/sdk/hooks/hook_context.rbs
 - sig/open_feature/sdk/hooks/hook_executor.rbs
 - sig/open_feature/sdk/hooks/logging_hook.rbs
+- sig/open_feature/sdk/isolated.rbs
 - sig/open_feature/sdk/provider.rbs
 - sig/open_feature/sdk/provider/error_code.rbs
 - sig/open_feature/sdk/provider/event_emitter.rbs