openfeature-sdk 0.6.4 → 0.6.5

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

@@ -0,0 +1,35 @@
+module OpenFeature
+  module SDK
+    module Provider
+      class InMemoryProvider
+        include Provider::EventEmitter
+
+        NAME: String
+
+        attr_reader metadata: ProviderMetadata
+
+        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
+        def update_flags: (Hash[String, untyped] new_flags) -> void
+
+        def fetch_boolean_value: (flag_key: String, default_value: bool, ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def fetch_string_value: (flag_key: String, default_value: String, ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def fetch_number_value: (flag_key: String, default_value: Numeric, ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def fetch_integer_value: (flag_key: String, default_value: Integer, ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def fetch_float_value: (flag_key: String, default_value: Float, ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def fetch_object_value: (flag_key: String, default_value: Array[untyped] | Hash[untyped, untyped], ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+
+        private
+
+        attr_reader flags: Hash[String, untyped]
+
+        def fetch_value: (flag_key: String, default_value: untyped, evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def emit_provider_changed: (Array[String] flag_keys) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module OpenFeature
+  module SDK
+    module Provider
+      class NoOpProvider
+        REASON_NO_OP: String
+        NAME: String
+
+        attr_reader metadata: ProviderMetadata
+
+        def initialize: () -> void
+
+        def fetch_boolean_value: (flag_key: String, default_value: bool, ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def fetch_string_value: (flag_key: String, default_value: String, ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def fetch_number_value: (flag_key: String, default_value: Numeric, ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def fetch_integer_value: (flag_key: String, default_value: Integer, ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def fetch_float_value: (flag_key: String, default_value: Float, ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def fetch_object_value: (flag_key: String, default_value: Array[untyped] | Hash[untyped, untyped], ?evaluation_context: EvaluationContext?) -> ResolutionDetails
+
+        private
+
+        def no_op: (untyped default_value) -> ResolutionDetails
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module OpenFeature
+  module SDK
+    module Provider
+      class ProviderMetadata < Struct[untyped]
+        attr_accessor name: String?
+
+        def initialize: (?name: String?) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module OpenFeature
+  module SDK
+    module Provider
+      module Reason
+        STATIC: String
+        DEFAULT: String
+        TARGETING_MATCH: String
+        SPLIT: String
+        CACHED: String
+        DISABLED: String
+        UNKNOWN: String
+        STALE: String
+        ERROR: String
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module OpenFeature
+  module SDK
+    module Provider
+      EMPTY_FLAG_METADATA: Hash[String, untyped]
+
+      class ResolutionDetails < Struct[untyped]
+        attr_accessor value: untyped
+        attr_accessor reason: String?
+        attr_accessor variant: String?
+        attr_accessor error_code: String?
+        attr_accessor error_message: String?
+
+        def initialize: (?value: untyped, ?reason: String?, ?variant: String?, ?error_code: String?, ?error_message: String?, ?flag_metadata: Hash[String, untyped]?) -> void
+
+        def flag_metadata: () -> Hash[String, untyped]
+      end
+    end
+  end
+end

data/sig/open_feature/sdk/provider.rbs

@@ -0,0 +1,24 @@
+module OpenFeature
+  module SDK
+    module Provider
+      interface _Provider
+        def fetch_boolean_value: (flag_key: String, default_value: bool, ?evaluation_context: EvaluationContext?) -> Provider::ResolutionDetails
+        def fetch_string_value: (flag_key: String, default_value: String, ?evaluation_context: EvaluationContext?) -> Provider::ResolutionDetails
+        def fetch_number_value: (flag_key: String, default_value: Numeric, ?evaluation_context: EvaluationContext?) -> Provider::ResolutionDetails
+        def fetch_integer_value: (flag_key: String, default_value: Integer, ?evaluation_context: EvaluationContext?) -> Provider::ResolutionDetails
+        def fetch_float_value: (flag_key: String, default_value: Float, ?evaluation_context: EvaluationContext?) -> Provider::ResolutionDetails
+        def fetch_object_value: (flag_key: String, default_value: Array[untyped] | Hash[untyped, untyped], ?evaluation_context: EvaluationContext?) -> Provider::ResolutionDetails
+      end
+
+      interface _LifecycleProvider
+        def init: (?EvaluationContext? evaluation_context) -> void
+        def shutdown: () -> void
+        def metadata: () -> ProviderMetadata
+      end
+
+      interface _TrackableProvider
+        def track: (String tracking_event_name, ?evaluation_context: EvaluationContext?, ?tracking_event_details: TrackingEventDetails?) -> void
+      end
+    end
+  end
+end

data/sig/open_feature/sdk/provider_event.rbs

@@ -0,0 +1,12 @@
+module OpenFeature
+  module SDK
+    module ProviderEvent
+      PROVIDER_READY: String
+      PROVIDER_ERROR: String
+      PROVIDER_CONFIGURATION_CHANGED: String
+      PROVIDER_STALE: String
+
+      ALL_EVENTS: Array[String]
+    end
+  end
+end

data/sig/open_feature/sdk/provider_initialization_error.rbs

@@ -0,0 +1,11 @@
+module OpenFeature
+  module SDK
+    class ProviderInitializationError < StandardError
+      attr_reader provider: untyped
+      attr_reader original_error: Exception?
+      attr_reader error_code: String
+
+      def initialize: (String message, ?provider: untyped, ?original_error: Exception?, ?error_code: String) -> void
+    end
+  end
+end

data/sig/open_feature/sdk/provider_state.rbs

@@ -0,0 +1,13 @@
+module OpenFeature
+  module SDK
+    module ProviderState
+      NOT_READY: String
+      READY: String
+      ERROR: String
+      STALE: String
+      FATAL: String
+
+      ALL_STATES: Array[String]
+    end
+  end
+end

data/sig/open_feature/sdk/provider_state_registry.rbs

@@ -0,0 +1,22 @@
+module OpenFeature
+  module SDK
+    class ProviderStateRegistry
+      def initialize: () -> void
+
+      def set_initial_state: (untyped provider, ?String state) -> void
+      def update_state_from_event: (untyped provider, String event_type, ?Hash[Symbol, untyped]? event_details) -> String
+      def get_state: (untyped provider) -> String
+      def get_details: (untyped provider) -> Hash[Symbol, untyped]
+      def remove_provider: (untyped provider) -> void
+      def tracked?: (untyped provider) -> bool
+      def ready?: (untyped provider) -> bool
+      def error?: (untyped provider) -> bool
+      def clear: () -> void
+
+      private
+
+      def state_from_event: (String event_type, ?Hash[Symbol, untyped]? event_details) -> String?
+      def state_from_error_event: (Hash[Symbol, untyped]? event_details) -> String
+    end
+  end
+end

data/sig/open_feature/sdk/telemetry.rbs

@@ -0,0 +1,29 @@
+module OpenFeature
+  module SDK
+    module Telemetry
+      EVENT_NAME: String
+
+      FLAG_KEY: String
+      CONTEXT_ID_KEY: String
+      ERROR_MESSAGE_KEY: String
+      ERROR_TYPE_KEY: String
+      PROVIDER_NAME_KEY: String
+      RESULT_REASON_KEY: String
+      RESULT_VALUE_KEY: String
+      RESULT_VARIANT_KEY: String
+      FLAG_SET_ID_KEY: String
+      VERSION_KEY: String
+
+      METADATA_KEY_MAP: Hash[String, String]
+
+      class EvaluationEvent < Struct[untyped]
+        attr_accessor name: String
+        attr_accessor attributes: Hash[String, untyped]
+
+        def initialize: (?name: String, ?attributes: Hash[String, untyped]) -> void
+      end
+
+      def self.create_evaluation_event: (hook_context: Hooks::HookContext, evaluation_details: EvaluationDetails?) -> EvaluationEvent
+    end
+  end
+end

data/sig/open_feature/sdk/thread_local_transaction_context_propagator.rbs

@@ -0,0 +1,12 @@
+module OpenFeature
+  module SDK
+    class ThreadLocalTransactionContextPropagator
+      include TransactionContextPropagator
+
+      THREAD_KEY: Symbol
+
+      def set_transaction_context: (EvaluationContext evaluation_context) -> void
+      def get_transaction_context: () -> EvaluationContext?
+    end
+  end
+end

data/sig/open_feature/sdk/tracking_event_details.rbs

@@ -0,0 +1,10 @@
+module OpenFeature
+  module SDK
+    class TrackingEventDetails
+      attr_reader value: Numeric?
+      attr_reader fields: Hash[String, untyped]
+
+      def initialize: (?value: Numeric?, **untyped fields) -> void
+    end
+  end
+end

data/sig/open_feature/sdk/transaction_context_propagator.rbs

@@ -0,0 +1,11 @@
+module OpenFeature
+  module SDK
+    interface _TransactionContextPropagator
+      def set_transaction_context: (EvaluationContext evaluation_context) -> void
+      def get_transaction_context: () -> EvaluationContext?
+    end
+
+    module TransactionContextPropagator : _TransactionContextPropagator
+    end
+  end
+end

data/sig/open_feature/sdk/version.rbs

@@ -0,0 +1,5 @@
+module OpenFeature
+  module SDK
+    VERSION: String
+  end
+end

data/sig/open_feature/sdk.rbs

@@ -0,0 +1,22 @@
+module OpenFeature
+  module SDK
+    # Delegated to API.instance via method_missing
+    def self.configure: () { (Configuration) -> void } -> void
+    def self.build_client: (?domain: String?, ?evaluation_context: EvaluationContext?) -> Client
+    def self.configuration: () -> Configuration
+    def self.provider: (?domain: String?) -> untyped?
+    def self.set_provider: (untyped provider, ?domain: String?) -> void
+    def self.set_provider_and_wait: (untyped provider, ?domain: String?) -> void
+    def self.hooks: () -> Array[untyped]
+    def self.add_hooks: (*Array[untyped] new_hooks) -> void
+    def self.evaluation_context: () -> EvaluationContext?
+    def self.add_handler: (String event_type, _ToProc handler) -> void
+    def self.remove_handler: (String event_type, _ToProc handler) -> void
+    def self.logger: () -> untyped?
+    def self.logger=: (untyped? new_logger) -> void
+    def self.set_transaction_context_propagator: (_TransactionContextPropagator propagator) -> void
+    def self.set_transaction_context: (EvaluationContext evaluation_context) -> void
+    def self.shutdown: () -> void
+    def self.provider_metadata: (?domain: String?) -> Provider::ProviderMetadata?
+  end
+end

metadata

@@ -1,142 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: openfeature-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.4
+  version: 0.6.5
 platform: ruby
 authors:
 - OpenFeature Authors
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: debug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: markly
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 3.12.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 3.12.0
-- !ruby/object:Gem::Dependency
-  name: standard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: standard-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.22.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.22.0
-- !ruby/object:Gem::Dependency
-  name: simplecov-cobertura
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: timecop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.9.10
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.9.10
-description: Ruby SDK for an the specifications for the open standard of feature flag
-  management
+dependencies: []
+description: Ruby SDK for the OpenFeature specification, an open standard for feature
+  flag management
 email:
 - cncf-openfeature-contributors@lists.cncf.io
 executables: []
@@ -149,6 +23,7 @@ files:
 - ".simplecov"
 - ".standard.yml"
 - ".tool-versions"
+- ".yardopts"
 - CHANGELOG.md
 - CLAUDE.md
 - CODEOWNERS
@@ -159,9 +34,12 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- SECURITY.md
+- Steepfile
 - cucumber.yml
-- docs/plans/2026-03-07-telemetry-utility-design.md
-- docs/plans/2026-03-07-telemetry-utility-plan.md
+- examples/basic_usage.rb
+- examples/custom_provider.rb
+- examples/rails_integration.rb
 - lib/open_feature/sdk.rb
 - lib/open_feature/sdk/api.rb
 - lib/open_feature/sdk/client.rb
@@ -194,17 +72,52 @@ files:
 - lib/open_feature/sdk/tracking_event_details.rb
 - lib/open_feature/sdk/transaction_context_propagator.rb
 - lib/open_feature/sdk/version.rb
+- openfeature-sdk.gemspec
+- rbs_collection.lock.yaml
+- rbs_collection.yaml
 - release-please-config.json
 - renovate.json
-homepage: https://github.com/open-feature/openfeature-ruby
+- sig/open_feature/sdk.rbs
+- sig/open_feature/sdk/api.rbs
+- sig/open_feature/sdk/client.rbs
+- sig/open_feature/sdk/client_metadata.rbs
+- sig/open_feature/sdk/configuration.rbs
+- sig/open_feature/sdk/evaluation_context.rbs
+- sig/open_feature/sdk/evaluation_context_builder.rbs
+- sig/open_feature/sdk/evaluation_details.rbs
+- sig/open_feature/sdk/event_dispatcher.rbs
+- sig/open_feature/sdk/hooks/hints.rbs
+- sig/open_feature/sdk/hooks/hook.rbs
+- 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/provider.rbs
+- sig/open_feature/sdk/provider/error_code.rbs
+- sig/open_feature/sdk/provider/event_emitter.rbs
+- sig/open_feature/sdk/provider/in_memory_provider.rbs
+- sig/open_feature/sdk/provider/no_op_provider.rbs
+- sig/open_feature/sdk/provider/provider_metadata.rbs
+- sig/open_feature/sdk/provider/reason.rbs
+- sig/open_feature/sdk/provider/resolution_details.rbs
+- sig/open_feature/sdk/provider_event.rbs
+- sig/open_feature/sdk/provider_initialization_error.rbs
+- sig/open_feature/sdk/provider_state.rbs
+- sig/open_feature/sdk/provider_state_registry.rbs
+- sig/open_feature/sdk/telemetry.rbs
+- sig/open_feature/sdk/thread_local_transaction_context_propagator.rbs
+- sig/open_feature/sdk/tracking_event_details.rbs
+- sig/open_feature/sdk/transaction_context_propagator.rbs
+- sig/open_feature/sdk/version.rbs
+homepage: https://github.com/open-feature/ruby-sdk
 licenses:
 - Apache-2.0
 metadata:
-  homepage_uri: https://github.com/open-feature/openfeature-ruby
-  source_code_uri: https://github.com/open-feature/openfeature-ruby
-  changelog_uri: https://github.com/open-feature/openfeature-ruby/blob/main/CHANGELOG.md
-  bug_tracker_uri: https://github.com/open-feature/openfeature-ruby/issues
-  documentation_uri: https://github.com/open-feature/openfeature-ruby/README.md
+  homepage_uri: https://github.com/open-feature/ruby-sdk
+  source_code_uri: https://github.com/open-feature/ruby-sdk
+  changelog_uri: https://github.com/open-feature/ruby-sdk/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/open-feature/ruby-sdk/issues
+  documentation_uri: https://github.com/open-feature/ruby-sdk#readme
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -219,7 +132,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: OpenFeature SDK for Ruby
 test_files: []

data/docs/plans/2026-03-07-telemetry-utility-design.md

@@ -1,98 +0,0 @@
-# Telemetry Utility Design
-
-## Overview
-
-Add an OTel-compatible telemetry utility to the OpenFeature Ruby SDK that creates
-structured evaluation events from hook context and evaluation details. This utility
-is dependency-free (no OTel gem required) and follows the pattern established by
-the Go SDK's `telemetry` package.
-
-Addresses: https://github.com/open-feature/ruby-sdk/issues/176
-
-## References
-
-- [OpenFeature Spec Appendix D (Observability)](https://openfeature.dev/specification/appendix-d/)
-- [OTel Semantic Conventions for Feature Flags](https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/)
-- [Go SDK telemetry package](https://github.com/open-feature/go-sdk/tree/main/openfeature/telemetry)
-- [JS SDK reference PR](https://github.com/open-feature/js-sdk/pull/1120)
-
-## Design Decisions
-
-1. **Single public method** accepting `hook_context:` and `evaluation_details:` keyword
-   arguments — mirrors the `finally` hook stage signature for zero-friction integration.
-2. **Returns a Struct** (`EvaluationEvent`) with `name` and `attributes` fields — matches
-   the SDK's existing Struct conventions (`ResolutionDetails`, `ClientMetadata`, etc.).
-3. **Constants in the Telemetry module directly** — flat namespace matching Go SDK and
-   existing Ruby SDK patterns (e.g., `Provider::Reason`).
-4. **Hard-coded metadata mappings only** — maps `contextId`, `flagSetId`, `version` from
-   flag metadata to OTel keys. Unknown metadata keys are ignored. Custom attributes can
-   be added via hooks in ruby-sdk-contrib.
-5. **No third-party dependencies** — pure data transformation using only standard library.
-
-## File Structure
-
-- `lib/open_feature/sdk/telemetry.rb` — module with constants, struct, and utility function
-- `spec/open_feature/sdk/telemetry_spec.rb` — tests
-- `lib/open_feature/sdk.rb` — add `require_relative "sdk/telemetry"`
-
-## Constants
-
-```ruby
-EVENT_NAME        = "feature_flag.evaluation"
-
-FLAG_KEY          = "feature_flag.key"
-CONTEXT_ID_KEY    = "feature_flag.context.id"
-ERROR_MESSAGE_KEY = "error.message"
-ERROR_TYPE_KEY    = "error.type"
-PROVIDER_NAME_KEY = "feature_flag.provider.name"
-RESULT_REASON_KEY = "feature_flag.result.reason"
-RESULT_VALUE_KEY  = "feature_flag.result.value"
-RESULT_VARIANT_KEY = "feature_flag.result.variant"
-FLAG_SET_ID_KEY   = "feature_flag.set.id"
-VERSION_KEY       = "feature_flag.version"
-```
-
-## Public API
-
-```ruby
-OpenFeature::SDK::Telemetry.create_evaluation_event(
-  hook_context:,        # Hooks::HookContext
-  evaluation_details:   # EvaluationDetails or nil
-) # => EvaluationEvent
-```
-
-Returns `EvaluationEvent = Struct.new(:name, :attributes, keyword_init: true)`.
-
-## Attribute Population Rules
-
-| Attribute | Source | Condition |
-|-----------|--------|-----------|
-| `feature_flag.key` | `hook_context.flag_key` | Always |
-| `feature_flag.provider.name` | `hook_context.provider_metadata.name` | When present |
-| `feature_flag.result.variant` | `evaluation_details.variant` | When present (takes precedence over value) |
-| `feature_flag.result.value` | `evaluation_details.value` | Only when variant is nil |
-| `feature_flag.result.reason` | `evaluation_details.reason.downcase` | When present |
-| `error.type` | `evaluation_details.error_code.downcase` | When error occurred |
-| `error.message` | `evaluation_details.error_message` | When error occurred |
-| `feature_flag.context.id` | `targeting_key` or metadata `contextId` | Metadata takes precedence |
-| `feature_flag.set.id` | metadata `flagSetId` | When present in flag_metadata |
-| `feature_flag.version` | metadata `version` | When present in flag_metadata |
-
-## Error Handling
-
-No defensive `rescue` in the utility — it is a pure data transformation. Nil inputs
-are handled via guard clauses. The calling hook is responsible for exception safety
-(consistent with the existing hook executor pattern).
-
-## Test Plan
-
-1. Happy path with all attributes populated
-2. Variant vs value precedence
-3. Enum downcasing (reason and error_code)
-4. Error attributes present only on error
-5. Nil evaluation_details
-6. Nil/empty flag_metadata
-7. Metadata contextId overrides targeting_key
-8. Targeting key fallback when no contextId
-9. Unknown metadata keys ignored
-10. Return type verification