openfeature-sdk 0.6.1 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac3b2793c1b6453e2525dcc04d7646fd4e5d61a87e6ade8b257754cf9b9c991c
-  data.tar.gz: c5aeedfe23851ef99e26024bf1db5f4ba38d7f669b9ea6b3e1e5f63d0693c1a6
+  metadata.gz: bd3ec1b654a844eaa7bcafe400d6d2075199fa49ba6823aad1c8e1ce8c05a526
+  data.tar.gz: 3d159cb4f4df832154cfa7a4657ee53f357827a3d55dcbe124bf4716248e24b8
 SHA512:
-  metadata.gz: 9aa41845c24248cf6eec381f4531fbfc301196ea748f3b3189333c4879c64a2dc1eda8a935e3514291dcbb5100c1668260e1b87bec837952e1eb1777ae083501
-  data.tar.gz: c162a21b0a5b4ee91f132e676440b84cf7862afccd689416f97e9b41f9284bf8b86de5050a1c32a3c98096ec39074cbb0ae1dcbe0d85d4db905d447f3baccd3d
+  metadata.gz: 66667a224162e00b882ad73b45e5d2825cc35f47007ca961749cc7115cbe1223d881be0cfff89eb4a5d3fd3f0235c2548f7a89420de9ff7bb3a6b0fd4bcada65
+  data.tar.gz: f799ac085e5593bc9b14a040ebddc8326c57ff46e36285ed0ea9b44008dd0d8d58a149a1c0f7fc9be50aeb3cf8d60ffc2859f2b3f9099d49e1db3df6f795b669

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.6.1"
+  ".": "0.6.3"
 }

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.6.3](https://github.com/open-feature/ruby-sdk/compare/v0.6.2...v0.6.3) (2026-03-07)
+
+
+### Features
+
+* close spec compliance gaps for OpenFeature v0.8.0 ([#237](https://github.com/open-feature/ruby-sdk/issues/237)) ([9a87d04](https://github.com/open-feature/ruby-sdk/commit/9a87d04d5f261ea06e073f405c15613db7099d8a))
+* enable Gherkin feature tests ([#50](https://github.com/open-feature/ruby-sdk/issues/50)) ([#233](https://github.com/open-feature/ruby-sdk/issues/233)) ([95845ba](https://github.com/open-feature/ruby-sdk/commit/95845ba6ec26357d9c0895d310361e411f85da11))
+
+
+### Bug Fixes
+
+* close remaining MUST-level spec compliance gaps ([#238](https://github.com/open-feature/ruby-sdk/issues/238)) ([1d08491](https://github.com/open-feature/ruby-sdk/commit/1d084911964c8672dd66b23834eec6f14e453749))
+
+## [0.6.2](https://github.com/open-feature/ruby-sdk/compare/v0.6.1...v0.6.2) (2026-03-07)
+
+
+### Features
+
+* add logging hook (spec Appendix A) ([#229](https://github.com/open-feature/ruby-sdk/issues/229)) ([2f681c9](https://github.com/open-feature/ruby-sdk/commit/2f681c910198d2bfa16389018f42ca9dc3270936))
+* add transaction context propagation (spec 3.3) ([#230](https://github.com/open-feature/ruby-sdk/issues/230)) ([0aff30f](https://github.com/open-feature/ruby-sdk/commit/0aff30f77a0b680341cfd3d1f43e9d1f0ede1b75))
+
 ## [0.6.1](https://github.com/open-feature/ruby-sdk/compare/v0.6.0...v0.6.1) (2026-03-05)
 
 

data/Gemfile

@@ -4,3 +4,6 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in openfeature-sdk.gemspec
 gemspec
+
+gem "cucumber", "~> 10.0", group: :test
+gem "logger", group: :test

data/Gemfile.lock

@@ -1,12 +1,40 @@
 PATH
   remote: .
   specs:
-    openfeature-sdk (0.6.1)
+    openfeature-sdk (0.6.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    builder (3.3.0)
+    cucumber (10.2.0)
+      base64 (~> 0.2)
+      builder (~> 3.2)
+      cucumber-ci-environment (> 9, < 12)
+      cucumber-core (> 15, < 17)
+      cucumber-cucumber-expressions (> 17, < 20)
+      cucumber-html-formatter (> 21, < 23)
+      diff-lcs (~> 1.5)
+      logger (~> 1.6)
+      mini_mime (~> 1.1)
+      multi_test (~> 1.1)
+      sys-uname (~> 1.3)
+    cucumber-ci-environment (11.0.0)
+    cucumber-core (16.2.0)
+      cucumber-gherkin (> 36, < 40)
+      cucumber-messages (> 31, < 33)
+      cucumber-tag-expressions (> 6, < 9)
+    cucumber-cucumber-expressions (19.0.0)
+      bigdecimal
+    cucumber-gherkin (39.0.0)
+      cucumber-messages (>= 31, < 33)
+    cucumber-html-formatter (22.3.0)
+      cucumber-messages (> 23, < 33)
+    cucumber-messages (32.2.0)
+    cucumber-tag-expressions (8.1.0)
     date (3.5.1)
     debug (1.11.1)
       irb (~> 1.10)
@@ -14,6 +42,7 @@ GEM
     diff-lcs (1.6.2)
     docile (1.4.1)
     erb (6.0.2)
+    ffi (1.17.3)
     io-console (0.8.2)
     irb (1.17.0)
       pp (>= 0.6.0)
@@ -23,7 +52,11 @@ GEM
     json (2.18.1)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
+    logger (1.7.0)
     markly (0.15.2)
+    memoist3 (1.0.0)
+    mini_mime (1.1.5)
+    multi_test (1.1.0)
     parallel (1.27.0)
     parser (3.3.10.2)
       ast (~> 2.4.1)
@@ -100,6 +133,9 @@ GEM
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.26.0)
     stringio (3.2.0)
+    sys-uname (1.5.0)
+      ffi (~> 1.1)
+      memoist3 (~> 1.0.0)
     timecop (0.9.10)
     tsort (0.2.0)
     unicode-display_width (3.2.0)
@@ -120,7 +156,9 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  cucumber (~> 10.0)
   debug
+  logger
   markly
   openfeature-sdk!
   rake (~> 13.0)

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.1">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.1&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.6.3">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.3&color=blue&style=for-the-badge" />
   </a>
 
   <!-- x-release-please-end -->
@@ -101,12 +101,12 @@ object = client.fetch_object_value(flag_key: 'object_value', default_value: { na
 | ✅      | [Providers](#providers)                                             | Integrate with a commercial, open source, or in-house feature management tool.                                                                               |
 | ✅      | [Targeting](#targeting)                                             | Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context).                           |
 | ✅      | [Hooks](#hooks)                                                     | Add functionality to various stages of the flag evaluation life-cycle.                                                                                       |
-| ❌      | [Logging](#logging)                                                 | Integrate with popular logging packages.                                                                                                                     |
+| ✅      | [Logging](#logging)                                                 | Integrate with popular logging packages.                                                                                                                     |
 | ✅      | [Domains](#domains)                                                 | Logically bind clients with providers.                                                                                                                       |
 | ✅      | [Eventing](#eventing)                                               | React to state changes in the provider or flag management system.                                                                                            |
 | ✅      | [Shutdown](#shutdown)                                               | Gracefully clean up a provider during application shutdown.                                                                                                  |
 | ✅      | [Tracking](#tracking)                                               | Associate user actions with feature flag evaluations for experimentation.                                                                                    |
-| ❌      | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread) |
+| ✅      | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread) |
 | ✅      | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                                          |
 
 <sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>
@@ -247,9 +247,27 @@ client.fetch_boolean_value(
 
 ### Logging
 
-Coming Soon! [Issue available](https://github.com/open-feature/ruby-sdk/issues/148) to work on.
+The SDK includes a built-in `LoggingHook` that provides structured log output for flag evaluations. It logs at the `before`, `after`, and `error` stages of the hook lifecycle.
 
-<!-- TODO: talk about logging config and include a code example -->
+```ruby
+# Use the SDK's default logger (from Configuration)
+OpenFeature::SDK.hooks << OpenFeature::SDK::Hooks::LoggingHook.new
+
+# Or provide your own logger
+logger = Logger.new($stdout)
+OpenFeature::SDK.hooks << OpenFeature::SDK::Hooks::LoggingHook.new(logger: logger)
+
+# Optionally include evaluation context in log output
+OpenFeature::SDK.hooks << OpenFeature::SDK::Hooks::LoggingHook.new(
+  logger: logger,
+  include_evaluation_context: true
+)
+```
+
+Log output uses a structured key=value format:
+- **before** (DEBUG): `stage=before domain=my-domain provider_name=my-provider flag_key=my-flag default_value=false`
+- **after** (DEBUG): includes `reason`, `variant`, and `value`
+- **error** (ERROR): includes `error_code` and `error_message`
 
 ### Domains
 
@@ -361,12 +379,44 @@ Check the documentation for your [provider](#providers) for more information.
 
 ### Transaction Context Propagation
 
-Coming Soon! [Issue available](https://github.com/open-feature/ruby-sdk/issues/150) to be worked on.
+Transaction context is a container for transaction-specific evaluation context (e.g. user id, user agent, IP).
+Transaction context can be set where specific data is available (e.g. an auth service or request handler) and by using the transaction context propagator it will automatically be applied to all flag evaluations within a transaction (e.g. a request or thread).
+
+The SDK ships with a `ThreadLocalTransactionContextPropagator` that stores context in `Thread.current`:
+
+```ruby
+# Set up the propagator
+OpenFeature::SDK.set_transaction_context_propagator(
+  OpenFeature::SDK::ThreadLocalTransactionContextPropagator.new
+)
+
+# Set transaction context (e.g. in a request middleware)
+OpenFeature::SDK.set_transaction_context(
+  OpenFeature::SDK::EvaluationContext.new(targeting_key: "user-123", "email" => "user@example.com")
+)
+
+# Transaction context is automatically merged during flag evaluation.
+# Merge precedence: invocation > client > transaction > API (global)
+client = OpenFeature::SDK.build_client
+client.fetch_boolean_value(flag_key: "my-flag", default_value: false)
+```
+
+You can implement a custom propagator by including the `TransactionContextPropagator` module:
 
-<!-- Transaction context is a container for transaction-specific evaluation context (e.g. user id, user agent, IP).
-Transaction context can be set where specific data is available (e.g. an auth service or request handler) and by using the transaction context propagator it will automatically be applied to all flag evaluations within a transaction (e.g. a request or thread). -->
+```ruby
+class MyRequestScopedPropagator
+  include OpenFeature::SDK::TransactionContextPropagator
 
-<!-- TODO: code example for global shutdown -->
+  def set_transaction_context(evaluation_context)
+    # Store context in your request-scoped storage
+    RequestStore[:openfeature_context] = evaluation_context
+  end
+
+  def get_transaction_context
+    RequestStore[:openfeature_context]
+  end
+end
+```
 
 ## Extending
 

data/Rakefile

@@ -7,4 +7,9 @@ RSpec::Core::RakeTask.new(:spec)
 
 require "standard/rake"
 
+desc "Run Cucumber Gherkin feature tests"
+task :cucumber do
+  sh "bundle exec cucumber"
+end
+
 task default: %i[spec standard]

data/cucumber.yml

@@ -0,0 +1,2 @@
+default: spec/open-feature-spec/specification/assets/gherkin --require features --tags "not @deprecated" --publish-quiet
+deprecated: spec/open-feature-spec/specification/assets/gherkin --require features --publish-quiet

data/lib/open_feature/sdk/api.rb

@@ -34,7 +34,7 @@ module OpenFeature
       include Singleton # Satisfies Flag Evaluation API Requirement 1.1.1
       extend Forwardable
 
-      def_delegators :configuration, :provider, :set_provider, :set_provider_and_wait, :hooks, :evaluation_context
+      def_delegators :configuration, :provider, :set_provider, :set_provider_and_wait, :hooks, :add_hooks, :evaluation_context
 
       def configuration
         @configuration ||= Configuration.new
@@ -54,6 +54,11 @@ module OpenFeature
         Client.new(provider: Provider::NoOpProvider.new, evaluation_context:)
       end
 
+      def provider_metadata(domain: nil)
+        prov = provider(domain: domain)
+        prov.metadata if prov&.respond_to?(:metadata)
+      end
+
       def add_handler(event_type, handler)
         configuration.add_handler(event_type, handler)
       end
@@ -70,6 +75,15 @@ module OpenFeature
         configuration.logger = new_logger
       end
 
+      def set_transaction_context_propagator(propagator)
+        configuration.transaction_context_propagator = propagator
+      end
+
+      def set_transaction_context(evaluation_context)
+        propagator = configuration.transaction_context_propagator
+        propagator&.set_transaction_context(evaluation_context)
+      end
+
       def shutdown
         configuration.shutdown
       end

data/lib/open_feature/sdk/client.rb

@@ -28,6 +28,10 @@ module OpenFeature
         @hooks = []
       end
 
+      def add_hooks(*new_hooks)
+        @hooks.concat(new_hooks.flatten)
+      end
+
       def provider_status
         OpenFeature::SDK.configuration.provider_state(@provider)
       end
@@ -49,11 +53,7 @@ module OpenFeature
       def track(tracking_event_name, evaluation_context: nil, tracking_event_details: nil)
         return unless @provider.respond_to?(:track)
 
-        built_context = EvaluationContextBuilder.new.call(
-          api_context: OpenFeature::SDK.evaluation_context,
-          client_context: self.evaluation_context,
-          invocation_context: evaluation_context
-        )
+        built_context = build_evaluation_context(evaluation_context)
 
         @provider.track(tracking_event_name, evaluation_context: built_context, tracking_event_details: tracking_event_details)
       end
@@ -74,31 +74,40 @@ module OpenFeature
       def fetch_details(type:, flag_key:, default_value:, evaluation_context: nil, invocation_hooks: [], hook_hints: nil)
         validate_default_value_type(type, default_value)
 
+        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]
+
+        # Check for short-circuit conditions (spec 1.7.6 + 1.7.7)
+        short_circuit_code = nil
         if OpenFeature::SDK.configuration.provider_tracked?(@provider)
-          error_code = short_circuit_error_code(provider_status)
-          if error_code
+          short_circuit_code = short_circuit_error_code(provider_status)
+        end
+
+        # Fast path: skip hook ceremony when no hooks are registered
+        if ordered_hooks.empty?
+          if short_circuit_code
             resolution = Provider::ResolutionDetails.new(
               value: default_value,
-              error_code: error_code,
+              error_code: short_circuit_code,
               reason: Provider::Reason::ERROR
             )
             return EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
           end
-        end
-
-        built_context = EvaluationContextBuilder.new.call(
-          api_context: OpenFeature::SDK.evaluation_context,
-          client_context: self.evaluation_context,
-          invocation_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]
 
-        # Fast path: skip hook ceremony when no hooks are registered
-        if ordered_hooks.empty?
-          return evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: built_context)
+          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: Provider::ErrorCode::GENERAL,
+              reason: Provider::Reason::ERROR,
+              error_message: e.message
+            )
+            return EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
+          end
         end
 
         hook_context = Hooks::HookContext.new(
@@ -119,8 +128,21 @@ module OpenFeature
         end
 
         executor = Hooks::HookExecutor.new(logger: OpenFeature::SDK.configuration.logger)
-        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)
+
+        if short_circuit_code
+          # Spec 1.7.6 + 1.7.7: short-circuit must still run error hooks and finally hooks
+          resolution = Provider::ResolutionDetails.new(
+            value: default_value,
+            error_code: short_circuit_code,
+            reason: Provider::Reason::ERROR
+          )
+          evaluation_details = EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
+          executor.run_short_circuit(ordered_hooks: ordered_hooks, hook_context: hook_context, hints: hints, evaluation_details: evaluation_details)
+          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)
+          end
         end
       end
 
@@ -136,6 +158,7 @@ module OpenFeature
           resolution_details.value = default_value
           resolution_details.error_code = Provider::ErrorCode::TYPE_MISMATCH
           resolution_details.reason = Provider::Reason::ERROR
+          resolution_details.variant = nil
         end
 
         EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution_details)
@@ -148,6 +171,18 @@ module OpenFeature
         end
       end
 
+      def build_evaluation_context(invocation_context)
+        propagator = OpenFeature::SDK.configuration.transaction_context_propagator
+        transaction_context = propagator&.get_transaction_context
+
+        EvaluationContextBuilder.new.call(
+          api_context: OpenFeature::SDK.evaluation_context,
+          transaction_context: transaction_context,
+          client_context: evaluation_context,
+          invocation_context: invocation_context
+        )
+      end
+
       def validate_default_value_type(type, default_value)
         expected_classes = TYPE_CLASS_MAP[type]
         unless expected_classes.any? { |klass| default_value.is_a?(klass) }

data/lib/open_feature/sdk/client_metadata.rb

@@ -2,6 +2,8 @@
 
 module OpenFeature
   module SDK
-    ClientMetadata = Struct.new(:domain, keyword_init: true)
+    ClientMetadata = Struct.new(:domain, keyword_init: true) do
+      alias_method :name, :domain
+    end
   end
 end

data/lib/open_feature/sdk/configuration.rb

@@ -17,7 +17,7 @@ module OpenFeature
     class Configuration
       extend Forwardable
 
-      attr_accessor :evaluation_context, :hooks
+      attr_accessor :evaluation_context, :hooks, :transaction_context_propagator
       attr_reader :logger
 
       def initialize
@@ -31,6 +31,10 @@ module OpenFeature
         @client_handlers_mutex = Mutex.new
       end
 
+      def add_hooks(*new_hooks)
+        @hooks.concat(new_hooks.flatten)
+      end
+
       def provider(domain: nil)
         @providers[domain] || @providers[nil]
       end
@@ -85,9 +89,11 @@ module OpenFeature
       end
 
       def shutdown
-        providers_to_shutdown = @provider_mutex.synchronize { @providers.values.uniq }
+        providers_to_shutdown = @provider_mutex.synchronize { @providers.values.uniq(&:object_id) }
 
         providers_to_shutdown.each do |prov|
+          # Spec 1.7.9: Set provider state to NOT_READY before shutdown
+          @provider_state_registry.set_initial_state(prov, ProviderState::NOT_READY)
           prov.shutdown if prov.respond_to?(:shutdown)
         rescue => e
           @logger&.warn("Error shutting down provider #{prov&.class&.name || "unknown"}: #{e.message}")
@@ -107,34 +113,46 @@ module OpenFeature
         @provider_mutex.synchronize do
           @providers.clear
         end
+        @hooks.clear
+        @evaluation_context = nil
+        @transaction_context_propagator = nil
       end
 
       def set_provider_internal(provider, domain:, wait_for_init:)
         # Capture evaluation context before acquiring mutex to prevent race conditions
         context_for_init = @evaluation_context
 
-        old_provider, provider_to_init = nil
+        old_provider = nil
+        needs_init = false
+        needs_shutdown = false
 
         @provider_mutex.synchronize do
           old_provider = @providers[domain]
 
-          # Remove old provider state to prevent memory leaks
-          @provider_state_registry.remove_provider(old_provider)
-
           new_providers = @providers.dup
           new_providers[domain] = provider
           @providers = new_providers
 
-          @provider_state_registry.set_initial_state(provider)
+          # 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
 
-          provider.send(:attach, self) if provider.is_a?(Provider::EventEmitter)
+          if needs_init
+            @provider_state_registry.set_initial_state(provider)
+            provider.send(:attach, self) if provider.is_a?(Provider::EventEmitter)
+          end
 
-          provider_to_init = provider
+          # 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)
+            still_bound = @providers.any? { |_, p| p.equal?(old_provider) }
+            needs_shutdown = !still_bound
+            @provider_state_registry.remove_provider(old_provider) unless still_bound
+          end
         end
 
         # Shutdown old provider outside mutex to avoid blocking other operations
-        # Only shutdown if it's a different provider to prevent race condition
-        if old_provider && old_provider != provider
+        if needs_shutdown
           begin
             old_provider.shutdown if old_provider.respond_to?(:shutdown)
           rescue => e
@@ -143,12 +161,17 @@ module OpenFeature
         end
 
         # Initialize provider outside the mutex to avoid blocking other operations
-        if wait_for_init
-          init_provider(provider_to_init, context_for_init, raise_on_error: true)
-        else
-          Thread.new do
-            init_provider(provider_to_init, context_for_init, raise_on_error: false)
+        if needs_init
+          if wait_for_init
+            init_provider(provider, context_for_init, raise_on_error: true)
+          else
+            Thread.new do
+              init_provider(provider, context_for_init, raise_on_error: false)
+            end
           end
+        elsif wait_for_init
+          # Provider already active; no init needed but still dispatch READY
+          dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY)
         end
       end
 
@@ -164,16 +187,22 @@ module OpenFeature
 
         dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY)
       rescue => e
+        # Spec 1.7.8: Propagate error code from provider if available
+        error_code = if e.respond_to?(:error_code) && e.error_code
+          e.error_code
+        else
+          Provider::ErrorCode::GENERAL
+        end
+
         dispatch_provider_event(provider, ProviderEvent::PROVIDER_ERROR,
-          error_code: Provider::ErrorCode::GENERAL,
+          error_code: error_code,
           message: e.message)
 
         if raise_on_error
-          # Re-raise as ProviderInitializationError for synchronous callers
           raise ProviderInitializationError.new(
             "Provider #{provider.class.name} initialization failed: #{e.message}",
             provider:,
-            error_code: Provider::ErrorCode::GENERAL,
+            error_code: error_code,
             original_error: e
           )
         end

data/lib/open_feature/sdk/evaluation_context_builder.rb

@@ -4,8 +4,8 @@ module OpenFeature
   module SDK
     # Used to combine evaluation contexts from different sources
     class EvaluationContextBuilder
-      def call(api_context:, client_context:, invocation_context:)
-        available_contexts = [api_context, client_context, invocation_context].compact
+      def call(api_context:, client_context:, invocation_context:, transaction_context: nil)
+        available_contexts = [api_context, transaction_context, client_context, invocation_context].compact
 
         return nil if available_contexts.empty?
 

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

@@ -18,6 +18,20 @@ module OpenFeature
           @logger = logger
         end
 
+        # Runs error hooks and finally hooks for a short-circuit evaluation
+        # (spec 1.7.6 + 1.7.7). Before hooks and after hooks are NOT run.
+        #
+        # @param ordered_hooks [Array] hooks in before-order
+        # @param hook_context [HookContext] the hook context
+        # @param hints [Hints] hook hints
+        # @param evaluation_details [EvaluationDetails] the short-circuit result
+        def run_short_circuit(ordered_hooks:, hook_context:, hints:, evaluation_details:)
+          error = StandardError.new(evaluation_details.error_code)
+          run_error_hooks(ordered_hooks, hook_context, error, hints)
+        ensure
+          run_finally_hooks(ordered_hooks, hook_context, evaluation_details, hints)
+        end
+
         # Executes the full hook lifecycle around the flag evaluation block.
         #
         # @param ordered_hooks [Array] hooks in before-order (API, Client, Invocation, Provider)
@@ -31,7 +45,15 @@ module OpenFeature
           begin
             run_before_hooks(ordered_hooks, hook_context, hints)
             evaluation_details = evaluate_block.call(hook_context)
-            run_after_hooks(ordered_hooks, hook_context, evaluation_details, hints)
+
+            # Spec 4.3.6: If evaluation resulted in an error (e.g. FLAG_NOT_FOUND,
+            # TYPE_MISMATCH), run error hooks instead of after hooks.
+            if evaluation_details.error_code
+              error = StandardError.new(evaluation_details.error_message || evaluation_details.error_code)
+              run_error_hooks(ordered_hooks, hook_context, error, hints)
+            else
+              run_after_hooks(ordered_hooks, hook_context, evaluation_details, hints)
+            end
           rescue => e
             run_error_hooks(ordered_hooks, hook_context, e, hints)
 

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module Hooks
+      class LoggingHook
+        include Hook
+
+        def initialize(logger: nil, include_evaluation_context: false)
+          @logger = logger
+          @include_evaluation_context = include_evaluation_context
+        end
+
+        def before(hook_context:, hints:)
+          logger&.debug { build_before_message(hook_context) }
+          nil
+        end
+
+        def after(hook_context:, evaluation_details:, hints:)
+          logger&.debug { build_after_message(hook_context, evaluation_details) }
+          nil
+        end
+
+        def error(hook_context:, exception:, hints:)
+          logger&.error { build_error_message(hook_context, exception) }
+          nil
+        end
+
+        private
+
+        def logger
+          @logger || OpenFeature::SDK.configuration.logger
+        end
+
+        def build_before_message(hook_context)
+          parts = base_parts("before", hook_context)
+          parts << "evaluation_context=#{format_context(hook_context.evaluation_context)}" if @include_evaluation_context
+          parts.join(" ")
+        end
+
+        def build_after_message(hook_context, evaluation_details)
+          parts = base_parts("after", hook_context)
+          parts << "reason=#{sanitize(evaluation_details.reason)}" if evaluation_details.reason
+          parts << "variant=#{sanitize(evaluation_details.variant)}" if evaluation_details.variant
+          parts << "value=#{sanitize(evaluation_details.value)}"
+          parts << "evaluation_context=#{format_context(hook_context.evaluation_context)}" if @include_evaluation_context
+          parts.join(" ")
+        end
+
+        def build_error_message(hook_context, exception)
+          parts = base_parts("error", hook_context)
+          error_code = exception.respond_to?(:error_code) ? exception.error_code : Provider::ErrorCode::GENERAL
+          parts << "error_code=#{sanitize(error_code)}"
+          parts << "error_message=#{sanitize(exception.message)}"
+          parts << "evaluation_context=#{format_context(hook_context.evaluation_context)}" if @include_evaluation_context
+          parts.join(" ")
+        end
+
+        def base_parts(stage, hook_context)
+          domain = hook_context.client_metadata&.domain
+          provider_name = hook_context.provider_metadata&.name
+          [
+            "stage=#{stage}",
+            "domain=#{sanitize(domain)}",
+            "provider_name=#{sanitize(provider_name)}",
+            "flag_key=#{sanitize(hook_context.flag_key)}",
+            "default_value=#{sanitize(hook_context.default_value)}"
+          ]
+        end
+
+        def format_context(evaluation_context)
+          return "" unless evaluation_context
+          fields = evaluation_context.fields.dup
+          fields["targeting_key"] = evaluation_context.targeting_key if evaluation_context.targeting_key
+          fields.map { |k, v| "#{sanitize(k)}=#{sanitize(v)}" }.join(", ")
+        end
+
+        def sanitize(value)
+          value.to_s.gsub(/[\n\r]/, " ")
+        end
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/hooks.rb

@@ -4,3 +4,4 @@ require_relative "hooks/hints"
 require_relative "hooks/hook"
 require_relative "hooks/hook_context"
 require_relative "hooks/hook_executor"
+require_relative "hooks/logging_hook"

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

@@ -29,8 +29,10 @@ module OpenFeature
         end
 
         def update_flags(new_flags)
+          old_keys = @flags.keys
           @flags = new_flags.dup
-          emit_provider_changed(new_flags.keys)
+          changed_keys = (old_keys | new_flags.keys)
+          emit_provider_changed(changed_keys)
         end
 
         def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)

data/lib/open_feature/sdk/thread_local_transaction_context_propagator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    class ThreadLocalTransactionContextPropagator
+      include TransactionContextPropagator
+
+      THREAD_KEY = :openfeature_transaction_context
+
+      def set_transaction_context(evaluation_context)
+        Thread.current[THREAD_KEY] = evaluation_context
+      end
+
+      def get_transaction_context
+        Thread.current[THREAD_KEY]
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/transaction_context_propagator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module TransactionContextPropagator
+      def set_transaction_context(evaluation_context)
+        raise NotImplementedError
+      end
+
+      def get_transaction_context
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module OpenFeature
   module SDK
-    VERSION = "0.6.1"
+    VERSION = "0.6.3"
   end
 end

data/lib/open_feature/sdk.rb

@@ -2,6 +2,8 @@
 
 require_relative "sdk/version"
 require_relative "sdk/api"
+require_relative "sdk/transaction_context_propagator"
+require_relative "sdk/thread_local_transaction_context_propagator"
 
 module OpenFeature
   # TODO: Add documentation

data/renovate.json

@@ -3,7 +3,7 @@
   "extends": [
     "config:recommended",
     ":automergeStableNonMajor",
-    "npm:unpublishSafe"
+    "security:minimumReleaseAgeNpm"
   ],
   "semanticCommits": "enabled"
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openfeature-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.3
 platform: ruby
 authors:
 - OpenFeature Authors
@@ -159,6 +159,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- cucumber.yml
 - lib/open_feature/sdk.rb
 - lib/open_feature/sdk/api.rb
 - lib/open_feature/sdk/client.rb
@@ -173,6 +174,7 @@ files:
 - lib/open_feature/sdk/hooks/hook.rb
 - 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/provider.rb
 - lib/open_feature/sdk/provider/error_code.rb
 - lib/open_feature/sdk/provider/event_emitter.rb
@@ -185,7 +187,9 @@ files:
 - lib/open_feature/sdk/provider_initialization_error.rb
 - lib/open_feature/sdk/provider_state.rb
 - lib/open_feature/sdk/provider_state_registry.rb
+- lib/open_feature/sdk/thread_local_transaction_context_propagator.rb
 - lib/open_feature/sdk/tracking_event_details.rb
+- lib/open_feature/sdk/transaction_context_propagator.rb
 - lib/open_feature/sdk/version.rb
 - release-please-config.json
 - renovate.json