openfeature-sdk 0.6.2 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 304772054cf10c0cc02870fdeb7a1a7412342912e3f8a08d80c33fe25bd99849
-  data.tar.gz: 6a27c2a8bf23074292594f4eec0ecd4dd9df11ddc1e3e48c4c7ff245e76a6381
+  metadata.gz: 4aa61c48f017d3311bfce9022a5e08d023ee1e2c09eb8799ff0e0a8424cf9fe3
+  data.tar.gz: 8c559636076a0ec01911e9057d57cde4e430a7bc4b2543835dcd90527e0f0c0e
 SHA512:
-  metadata.gz: bcaacd882ecdf0ebd0643e1a839bae3d4efb02deb30f2128c5feca91c93e85bee65b755147cf4bef6edabc010875746b777cd4570f26161451a620db396e02e8
-  data.tar.gz: 5a6ba82992f4d8e960d350a573e48a5e015c9b8eb953737354a4573d0a9f89ca6c4615553d0240a91c1490aad8fc3e1c2ca4bfeddc64d0b1203835ede55e1c77
+  metadata.gz: 0f683b0d315b225259e540fb9f7d86f60a7e334c1501b7f05d45d677d1e7ee6cfb951b463514c05d9c64b5b413935d1bdf95cd684aa5f05136ed87a6cf2ba122
+  data.tar.gz: 618dcac7749c461bb77b92f7f7b68e2071b4b71825d05330bb18a08df3a929019ef0fa8d12d79b117fdd3fce431d48f5e15d2f90aa884fa4f28b1226229f9db0

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.6.2"
+  ".": "0.6.4"
 }

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.6.4](https://github.com/open-feature/ruby-sdk/compare/v0.6.3...v0.6.4) (2026-03-07)
+
+
+### Features
+
+* add OTel-compatible telemetry utility ([#240](https://github.com/open-feature/ruby-sdk/issues/240)) ([a03e524](https://github.com/open-feature/ruby-sdk/commit/a03e524681a38c8762257049fae360fa15fcfba3))
+
+## [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)
 
 

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.2)
+    openfeature-sdk (0.6.4)
 
 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.2">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.2&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.6.4">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.4&color=blue&style=for-the-badge" />
   </a>
 
   <!-- x-release-please-end -->

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/docs/plans/2026-03-07-telemetry-utility-design.md

@@ -0,0 +1,98 @@
+# 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

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

@@ -0,0 +1,578 @@
+# Telemetry Utility Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a dependency-free `OpenFeature::SDK::Telemetry` module that creates OTel-compatible evaluation events from hook context and evaluation details.
+
+**Architecture:** Single module (`Telemetry`) in one file with constants, a Struct, and one public `module_function`. Designed for consumption in a hook's `finally` stage. No third-party dependencies.
+
+**Tech Stack:** Ruby >= 3.1, RSpec, Standard Ruby (linter)
+
+---
+
+### Task 1: Create telemetry module with constants and struct
+
+**Files:**
+- Create: `lib/open_feature/sdk/telemetry.rb`
+
+**Step 1: Create the module file with constants and struct**
+
+```ruby
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module Telemetry
+      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"
+
+      METADATA_KEY_MAP = {
+        "contextId" => CONTEXT_ID_KEY,
+        "flagSetId" => FLAG_SET_ID_KEY,
+        "version" => VERSION_KEY
+      }.freeze
+
+      EvaluationEvent = Struct.new(:name, :attributes, keyword_init: true)
+    end
+  end
+end
+```
+
+**Step 2: Wire up the require**
+
+Modify: `lib/open_feature/sdk.rb` — add `require_relative "sdk/telemetry"` after the existing requires (line 3 area).
+
+**Step 3: Verify it loads**
+
+Run: `bundle exec ruby -e "require 'open_feature/sdk'; puts OpenFeature::SDK::Telemetry::EVENT_NAME"`
+Expected: `feature_flag.evaluation`
+
+**Step 4: Commit**
+
+```bash
+git add lib/open_feature/sdk/telemetry.rb lib/open_feature/sdk.rb
+git commit -s -S -m "feat(telemetry): add Telemetry module with OTel constants and EvaluationEvent struct"
+```
+
+---
+
+### Task 2: Write tests for happy path and return type
+
+**Files:**
+- Create: `spec/open_feature/sdk/telemetry_spec.rb`
+
+**Step 1: Write the test file with happy path and return type tests**
+
+```ruby
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe OpenFeature::SDK::Telemetry do
+  let(:client_metadata) { OpenFeature::SDK::ClientMetadata.new(domain: "test-domain") }
+  let(:provider_metadata) { OpenFeature::SDK::Provider::ProviderMetadata.new(name: "test-provider") }
+  let(:evaluation_context) { OpenFeature::SDK::EvaluationContext.new(targeting_key: "user-123") }
+
+  let(:hook_context) do
+    OpenFeature::SDK::Hooks::HookContext.new(
+      flag_key: "my-flag",
+      flag_value_type: :boolean,
+      default_value: false,
+      evaluation_context: evaluation_context,
+      client_metadata: client_metadata,
+      provider_metadata: provider_metadata
+    )
+  end
+
+  let(:flag_metadata) do
+    {
+      "contextId" => "ctx-456",
+      "flagSetId" => "set-789",
+      "version" => "v1.0"
+    }
+  end
+
+  let(:resolution_details) do
+    OpenFeature::SDK::Provider::ResolutionDetails.new(
+      value: true,
+      reason: "TARGETING_MATCH",
+      variant: "enabled",
+      flag_metadata: flag_metadata
+    )
+  end
+
+  let(:evaluation_details) do
+    OpenFeature::SDK::EvaluationDetails.new(
+      flag_key: "my-flag",
+      resolution_details: resolution_details
+    )
+  end
+
+  describe ".create_evaluation_event" do
+    context "with full data" do
+      it "returns an EvaluationEvent with all attributes populated" do
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: evaluation_details
+        )
+
+        expect(event).to be_a(OpenFeature::SDK::Telemetry::EvaluationEvent)
+        expect(event.name).to eq("feature_flag.evaluation")
+        expect(event.attributes).to eq(
+          "feature_flag.key" => "my-flag",
+          "feature_flag.provider.name" => "test-provider",
+          "feature_flag.result.variant" => "enabled",
+          "feature_flag.result.reason" => "targeting_match",
+          "feature_flag.context.id" => "ctx-456",
+          "feature_flag.set.id" => "set-789",
+          "feature_flag.version" => "v1.0"
+        )
+      end
+    end
+  end
+end
+```
+
+**Step 2: Run the test to verify it fails**
+
+Run: `bundle exec rspec spec/open_feature/sdk/telemetry_spec.rb`
+Expected: FAIL — `NoMethodError: undefined method 'create_evaluation_event'`
+
+**Step 3: Commit the failing test**
+
+```bash
+git add spec/open_feature/sdk/telemetry_spec.rb
+git commit -s -S -m "test(telemetry): add failing test for happy path"
+```
+
+---
+
+### Task 3: Implement create_evaluation_event
+
+**Files:**
+- Modify: `lib/open_feature/sdk/telemetry.rb`
+
+**Step 1: Add the implementation to the Telemetry module**
+
+Add after the `EvaluationEvent` struct definition:
+
+```ruby
+      module_function
+
+      def create_evaluation_event(hook_context:, evaluation_details:)
+        attributes = {FLAG_KEY => hook_context.flag_key}
+
+        provider_name = hook_context.provider_metadata&.name
+        attributes[PROVIDER_NAME_KEY] = provider_name if provider_name
+
+        targeting_key = hook_context.evaluation_context&.targeting_key
+        attributes[CONTEXT_ID_KEY] = targeting_key if targeting_key
+
+        if evaluation_details
+          if evaluation_details.variant
+            attributes[RESULT_VARIANT_KEY] = evaluation_details.variant
+          else
+            attributes[RESULT_VALUE_KEY] = evaluation_details.value
+          end
+
+          if evaluation_details.reason
+            attributes[RESULT_REASON_KEY] = evaluation_details.reason.downcase
+          end
+
+          if evaluation_details.error_code
+            attributes[ERROR_TYPE_KEY] = evaluation_details.error_code.downcase
+          end
+
+          if evaluation_details.error_message
+            attributes[ERROR_MESSAGE_KEY] = evaluation_details.error_message
+          end
+
+          extract_metadata(evaluation_details.flag_metadata, attributes)
+        end
+
+        EvaluationEvent.new(name: EVENT_NAME, attributes: attributes)
+      end
+
+      def extract_metadata(flag_metadata, attributes)
+        return unless flag_metadata
+
+        METADATA_KEY_MAP.each do |metadata_key, otel_key|
+          value = flag_metadata[metadata_key]
+          attributes[otel_key] = value unless value.nil?
+        end
+      end
+
+      private_class_method :extract_metadata
+```
+
+**Step 2: Run the test to verify it passes**
+
+Run: `bundle exec rspec spec/open_feature/sdk/telemetry_spec.rb`
+Expected: PASS (1 example, 0 failures)
+
+**Step 3: Commit**
+
+```bash
+git add lib/open_feature/sdk/telemetry.rb
+git commit -s -S -m "feat(telemetry): implement create_evaluation_event"
+```
+
+---
+
+### Task 4: Add tests for variant vs value precedence
+
+**Files:**
+- Modify: `spec/open_feature/sdk/telemetry_spec.rb`
+
+**Step 1: Add variant/value precedence tests**
+
+Add inside the `describe ".create_evaluation_event"` block:
+
+```ruby
+    context "variant vs value precedence" do
+      it "uses variant when present and omits value" do
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: evaluation_details
+        )
+
+        expect(event.attributes).to have_key("feature_flag.result.variant")
+        expect(event.attributes).not_to have_key("feature_flag.result.value")
+      end
+
+      it "uses value when variant is nil" do
+        resolution = OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: "blue",
+          reason: "STATIC"
+        )
+        details = OpenFeature::SDK::EvaluationDetails.new(
+          flag_key: "color-flag",
+          resolution_details: resolution
+        )
+
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: details
+        )
+
+        expect(event.attributes["feature_flag.result.value"]).to eq("blue")
+        expect(event.attributes).not_to have_key("feature_flag.result.variant")
+      end
+    end
+```
+
+**Step 2: Run tests**
+
+Run: `bundle exec rspec spec/open_feature/sdk/telemetry_spec.rb`
+Expected: PASS (3 examples, 0 failures)
+
+**Step 3: Commit**
+
+```bash
+git add spec/open_feature/sdk/telemetry_spec.rb
+git commit -s -S -m "test(telemetry): add variant vs value precedence tests"
+```
+
+---
+
+### Task 5: Add tests for enum downcasing
+
+**Files:**
+- Modify: `spec/open_feature/sdk/telemetry_spec.rb`
+
+**Step 1: Add enum downcasing tests**
+
+Add inside the `describe ".create_evaluation_event"` block:
+
+```ruby
+    context "enum downcasing" do
+      it "downcases reason to OTel convention" do
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: evaluation_details
+        )
+
+        expect(event.attributes["feature_flag.result.reason"]).to eq("targeting_match")
+      end
+
+      it "downcases error_code to OTel convention" do
+        resolution = OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: false,
+          reason: "ERROR",
+          error_code: "FLAG_NOT_FOUND",
+          error_message: "Flag not found"
+        )
+        details = OpenFeature::SDK::EvaluationDetails.new(
+          flag_key: "missing-flag",
+          resolution_details: resolution
+        )
+
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: details
+        )
+
+        expect(event.attributes["error.type"]).to eq("flag_not_found")
+        expect(event.attributes["feature_flag.result.reason"]).to eq("error")
+      end
+    end
+```
+
+**Step 2: Run tests**
+
+Run: `bundle exec rspec spec/open_feature/sdk/telemetry_spec.rb`
+Expected: PASS (5 examples, 0 failures)
+
+**Step 3: Commit**
+
+```bash
+git add spec/open_feature/sdk/telemetry_spec.rb
+git commit -s -S -m "test(telemetry): add enum downcasing tests"
+```
+
+---
+
+### Task 6: Add tests for error attributes and nil evaluation_details
+
+**Files:**
+- Modify: `spec/open_feature/sdk/telemetry_spec.rb`
+
+**Step 1: Add error and nil evaluation_details tests**
+
+Add inside the `describe ".create_evaluation_event"` block:
+
+```ruby
+    context "error attributes" do
+      it "includes error attributes only when error occurred" do
+        resolution = OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: false,
+          reason: "ERROR",
+          error_code: "PARSE_ERROR",
+          error_message: "Could not parse flag"
+        )
+        details = OpenFeature::SDK::EvaluationDetails.new(
+          flag_key: "bad-flag",
+          resolution_details: resolution
+        )
+
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: details
+        )
+
+        expect(event.attributes["error.type"]).to eq("parse_error")
+        expect(event.attributes["error.message"]).to eq("Could not parse flag")
+      end
+
+      it "omits error attributes when no error" do
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: evaluation_details
+        )
+
+        expect(event.attributes).not_to have_key("error.type")
+        expect(event.attributes).not_to have_key("error.message")
+      end
+    end
+
+    context "nil evaluation_details" do
+      it "returns event with only flag_key and available context" do
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: nil
+        )
+
+        expect(event.name).to eq("feature_flag.evaluation")
+        expect(event.attributes).to eq(
+          "feature_flag.key" => "my-flag",
+          "feature_flag.provider.name" => "test-provider",
+          "feature_flag.context.id" => "user-123"
+        )
+      end
+    end
+```
+
+**Step 2: Run tests**
+
+Run: `bundle exec rspec spec/open_feature/sdk/telemetry_spec.rb`
+Expected: PASS (8 examples, 0 failures)
+
+**Step 3: Commit**
+
+```bash
+git add spec/open_feature/sdk/telemetry_spec.rb
+git commit -s -S -m "test(telemetry): add error attributes and nil evaluation_details tests"
+```
+
+---
+
+### Task 7: Add tests for flag metadata and context ID precedence
+
+**Files:**
+- Modify: `spec/open_feature/sdk/telemetry_spec.rb`
+
+**Step 1: Add metadata and context ID tests**
+
+Add inside the `describe ".create_evaluation_event"` block:
+
+```ruby
+    context "flag metadata" do
+      it "ignores nil flag_metadata" do
+        resolution = OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: true,
+          variant: "on"
+        )
+        details = OpenFeature::SDK::EvaluationDetails.new(
+          flag_key: "my-flag",
+          resolution_details: resolution
+        )
+
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: details
+        )
+
+        expect(event.attributes).not_to have_key("feature_flag.set.id")
+        expect(event.attributes).not_to have_key("feature_flag.version")
+      end
+
+      it "ignores empty flag_metadata" do
+        resolution = OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: true,
+          variant: "on",
+          flag_metadata: {}
+        )
+        details = OpenFeature::SDK::EvaluationDetails.new(
+          flag_key: "my-flag",
+          resolution_details: resolution
+        )
+
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: details
+        )
+
+        expect(event.attributes).not_to have_key("feature_flag.set.id")
+        expect(event.attributes).not_to have_key("feature_flag.version")
+      end
+
+      it "ignores unknown metadata keys" do
+        resolution = OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: true,
+          variant: "on",
+          flag_metadata: {"customKey" => "custom-value", "anotherKey" => 42}
+        )
+        details = OpenFeature::SDK::EvaluationDetails.new(
+          flag_key: "my-flag",
+          resolution_details: resolution
+        )
+
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: details
+        )
+
+        expect(event.attributes).not_to have_key("customKey")
+        expect(event.attributes).not_to have_key("anotherKey")
+      end
+    end
+
+    context "context ID precedence" do
+      it "uses metadata contextId over targeting_key" do
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: evaluation_details
+        )
+
+        # flag_metadata has contextId "ctx-456", targeting_key is "user-123"
+        expect(event.attributes["feature_flag.context.id"]).to eq("ctx-456")
+      end
+
+      it "falls back to targeting_key when no contextId in metadata" do
+        resolution = OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: true,
+          variant: "on",
+          flag_metadata: {"flagSetId" => "set-1"}
+        )
+        details = OpenFeature::SDK::EvaluationDetails.new(
+          flag_key: "my-flag",
+          resolution_details: resolution
+        )
+
+        event = described_class.create_evaluation_event(
+          hook_context: hook_context,
+          evaluation_details: details
+        )
+
+        expect(event.attributes["feature_flag.context.id"]).to eq("user-123")
+      end
+
+      it "omits context ID when neither targeting_key nor contextId available" do
+        bare_context = OpenFeature::SDK::EvaluationContext.new(env: "prod")
+        bare_hook_context = OpenFeature::SDK::Hooks::HookContext.new(
+          flag_key: "my-flag",
+          flag_value_type: :boolean,
+          default_value: false,
+          evaluation_context: bare_context
+        )
+        resolution = OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: true,
+          variant: "on"
+        )
+        details = OpenFeature::SDK::EvaluationDetails.new(
+          flag_key: "my-flag",
+          resolution_details: resolution
+        )
+
+        event = described_class.create_evaluation_event(
+          hook_context: bare_hook_context,
+          evaluation_details: details
+        )
+
+        expect(event.attributes).not_to have_key("feature_flag.context.id")
+      end
+    end
+```
+
+**Step 2: Run tests**
+
+Run: `bundle exec rspec spec/open_feature/sdk/telemetry_spec.rb`
+Expected: PASS (14 examples, 0 failures)
+
+**Step 3: Commit**
+
+```bash
+git add spec/open_feature/sdk/telemetry_spec.rb
+git commit -s -S -m "test(telemetry): add flag metadata and context ID precedence tests"
+```
+
+---
+
+### Task 8: Run full suite and lint
+
+**Step 1: Run full test suite**
+
+Run: `bundle exec rspec`
+Expected: All existing tests still pass, plus 14 new telemetry tests.
+
+**Step 2: Run linter**
+
+Run: `bundle exec standardrb`
+Expected: No offenses. If any, fix with `bundle exec standardrb --fix`.
+
+**Step 3: Final commit if lint fixes needed**
+
+```bash
+git add -A
+git commit -s -S -m "style(telemetry): fix standardrb lint issues"
+```

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

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
@@ -70,27 +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)
 
-        if OpenFeature::SDK.configuration.provider_tracked?(@provider)
-          error_code = short_circuit_error_code(provider_status)
-          if error_code
-            resolution = Provider::ResolutionDetails.new(
-              value: default_value,
-              error_code: error_code,
-              reason: Provider::Reason::ERROR
-            )
-            return EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
-          end
-        end
-
         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)
+          short_circuit_code = short_circuit_error_code(provider_status)
+        end
+
         # 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)
+          if short_circuit_code
+            resolution = Provider::ResolutionDetails.new(
+              value: default_value,
+              error_code: short_circuit_code,
+              reason: Provider::Reason::ERROR
+            )
+            return EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
+          end
+
+          begin
+            return evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: built_context)
+          rescue => e
+            resolution = Provider::ResolutionDetails.new(
+              value: default_value,
+              error_code: 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(
@@ -111,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
 
@@ -128,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)

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

@@ -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/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/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/telemetry.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module Telemetry
+      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"
+
+      METADATA_KEY_MAP = {
+        "contextId" => CONTEXT_ID_KEY,
+        "flagSetId" => FLAG_SET_ID_KEY,
+        "version" => VERSION_KEY
+      }.freeze
+
+      EvaluationEvent = Struct.new(:name, :attributes, keyword_init: true)
+
+      module_function
+
+      def create_evaluation_event(hook_context:, evaluation_details:)
+        attributes = {FLAG_KEY => hook_context.flag_key}
+
+        provider_name = hook_context.provider_metadata&.name
+        attributes[PROVIDER_NAME_KEY] = provider_name if provider_name
+
+        targeting_key = hook_context.evaluation_context&.targeting_key
+        # Set from targeting_key; may be overridden by contextId in flag metadata below
+        attributes[CONTEXT_ID_KEY] = targeting_key if targeting_key
+
+        if evaluation_details
+          if evaluation_details.variant
+            attributes[RESULT_VARIANT_KEY] = evaluation_details.variant
+          else
+            attributes[RESULT_VALUE_KEY] = evaluation_details.value
+          end
+
+          if evaluation_details.reason
+            attributes[RESULT_REASON_KEY] = evaluation_details.reason.downcase
+          end
+
+          if evaluation_details.error_code
+            attributes[ERROR_TYPE_KEY] = evaluation_details.error_code.downcase
+          end
+
+          if evaluation_details.error_message
+            attributes[ERROR_MESSAGE_KEY] = evaluation_details.error_message
+          end
+
+          extract_metadata(evaluation_details.flag_metadata, attributes)
+        end
+
+        EvaluationEvent.new(name: EVENT_NAME, attributes: attributes.freeze)
+      end
+
+      def extract_metadata(flag_metadata, attributes)
+        return unless flag_metadata
+
+        METADATA_KEY_MAP.each do |metadata_key, otel_key|
+          value = flag_metadata[metadata_key]
+          attributes[otel_key] = value unless value.nil?
+        end
+      end
+
+      private_class_method :extract_metadata
+    end
+  end
+end

data/lib/open_feature/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module OpenFeature
   module SDK
-    VERSION = "0.6.2"
+    VERSION = "0.6.4"
   end
 end

data/lib/open_feature/sdk.rb

@@ -2,6 +2,7 @@
 
 require_relative "sdk/version"
 require_relative "sdk/api"
+require_relative "sdk/telemetry"
 require_relative "sdk/transaction_context_propagator"
 require_relative "sdk/thread_local_transaction_context_propagator"
 

data/renovate.json

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openfeature-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.6.4
 platform: ruby
 authors:
 - OpenFeature Authors
@@ -159,6 +159,9 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- cucumber.yml
+- docs/plans/2026-03-07-telemetry-utility-design.md
+- docs/plans/2026-03-07-telemetry-utility-plan.md
 - lib/open_feature/sdk.rb
 - lib/open_feature/sdk/api.rb
 - lib/open_feature/sdk/client.rb
@@ -186,6 +189,7 @@ 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/telemetry.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