openfeature-sdk 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36540a362c2f482ce84d2aa8ba3a6efd9b5d68fe7881ed4037f1422ad85f5525
-  data.tar.gz: 4f7e6a764074d50467949e056b0d50be794df0a67323bb80c5e34a724236314b
+  metadata.gz: ac3b2793c1b6453e2525dcc04d7646fd4e5d61a87e6ade8b257754cf9b9c991c
+  data.tar.gz: c5aeedfe23851ef99e26024bf1db5f4ba38d7f669b9ea6b3e1e5f63d0693c1a6
 SHA512:
-  metadata.gz: b77f6731c17b537069bbf72cf4760e88293bc59c9ae147079ff3b24ac6ac7f1b18b42b49e29fd1a04a85a6054d0a43834289561c06d6b342ba579ec23d510ef8
-  data.tar.gz: 077d8a3f20c396c82413dad70b9a93cff0cd27a76ff8034f67c50bfa0d08235e3424755a4cd33b81c39fed962d7a62e40d1f257d3bbc4e87bac787d0e315b3fb
+  metadata.gz: 9aa41845c24248cf6eec381f4531fbfc301196ea748f3b3189333c4879c64a2dc1eda8a935e3514291dcbb5100c1668260e1b87bec837952e1eb1777ae083501
+  data.tar.gz: c162a21b0a5b4ee91f132e676440b84cf7862afccd689416f97e9b41f9284bf8b86de5050a1c32a3c98096ec39074cbb0ae1dcbe0d85d4db905d447f3baccd3d

data/.release-please-manifest.json

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

data/.ruby-version

@@ -1 +1 @@
-3.4.8
+4.0.1

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.8
+ruby 4.0.1

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.6.1](https://github.com/open-feature/ruby-sdk/compare/v0.6.0...v0.6.1) (2026-03-05)
+
+
+### Features
+
+* add flag metadata defaulting and immutability ([#221](https://github.com/open-feature/ruby-sdk/issues/221)) ([a300fc5](https://github.com/open-feature/ruby-sdk/commit/a300fc559293169f22eb1ce26f738cdee664cd26))
+* add hook data per-hook mutable state ([#222](https://github.com/open-feature/ruby-sdk/issues/222)) ([28518a0](https://github.com/open-feature/ruby-sdk/commit/28518a0e08143d167b9d34c86e57a583fe5ee0de))
+* add InMemoryProvider context callbacks and event emission ([#224](https://github.com/open-feature/ruby-sdk/issues/224)) ([0a148f6](https://github.com/open-feature/ruby-sdk/commit/0a148f66abc815fc2ec9fd70027075125dbd504a))
+* add shutdown API, provider status, and status short-circuit ([#223](https://github.com/open-feature/ruby-sdk/issues/223)) ([f9c32ad](https://github.com/open-feature/ruby-sdk/commit/f9c32ad1b467af25697423a542bc568597f39743))
+* implement Tracking API (spec section 6) ([#227](https://github.com/open-feature/ruby-sdk/issues/227)) ([5576fce](https://github.com/open-feature/ruby-sdk/commit/5576fce1c3bcf6e7510d8957c7e40e85c4b83b6f))
+* populate event details payload with error_code and message ([#225](https://github.com/open-feature/ruby-sdk/issues/225)) ([a185003](https://github.com/open-feature/ruby-sdk/commit/a185003dc09a69b2dda1fe569d1f82c45979cdad))
+
+## [0.6.0](https://github.com/open-feature/ruby-sdk/compare/v0.5.1...v0.6.0) (2026-03-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* add Ruby 4.0 support, require minimum Ruby 3.4 ([#217](https://github.com/open-feature/ruby-sdk/issues/217))
+
+### Features
+
+* add Ruby 4.0 support, require minimum Ruby 3.4 ([#217](https://github.com/open-feature/ruby-sdk/issues/217)) ([f38ba40](https://github.com/open-feature/ruby-sdk/commit/f38ba40b31beb650ba475c631947fc7969e476fa))
+
 ## [0.5.1](https://github.com/open-feature/ruby-sdk/compare/v0.5.0...v0.5.1) (2026-03-04)
 
 

data/CLAUDE.md

@@ -2,71 +2,50 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Project Overview
+## Overview
 
-OpenFeature Ruby SDK — implements the [OpenFeature specification](https://openfeature.dev) (v0.8.0) for vendor-agnostic feature flag management. Published as the `openfeature-sdk` gem. Pure Ruby, no runtime dependencies. Requires Ruby >= 3.1.
+This is the official OpenFeature SDK for Ruby — an implementation of the [OpenFeature specification](https://openfeature.dev) providing a vendor-agnostic API for feature flag evaluation. Published as the `openfeature-sdk` gem. Requires Ruby >= 3.1.
 
 ## Commands
 
-```bash
-# Install dependencies
-bundle install
+- **Run all tests:** `bundle exec rspec`
+- **Run a single test file:** `bundle exec rspec spec/open_feature/sdk/client_spec.rb`
+- **Run a specific test by line:** `bundle exec rspec spec/open_feature/sdk/client_spec.rb:43`
+- **Lint:** `bundle exec standardrb`
+- **Lint with autofix:** `bundle exec standardrb --fix`
+- **Default rake (tests + lint):** `bundle exec rake`
 
-# Run full test suite + linting (default rake task)
-bundle exec rake
+Note: Linting uses [Standard Ruby](https://github.com/standardrb/standard) (configured via the `standard` gem), which enforces double-quoted strings and its own opinionated style. There is no `.rubocop.yml` — Standard manages RuboCop configuration internally. Do not use `bundle exec rubocop` directly as a stale RuboCop server may apply different rules; always use `bundle exec standardrb`.
 
-# Run tests only
-bundle exec rspec
-
-# Run a single test file
-bundle exec rspec spec/open_feature/sdk/client_spec.rb
-
-# Run a specific test by line number
-bundle exec rspec spec/open_feature/sdk/client_spec.rb:40
-
-# Lint (StandardRB with performance plugin)
-bundle exec rake standard
+## Architecture
 
-# Auto-fix lint issues
-bundle exec standardrb --fix
-```
+### Entry point and API singleton
 
-## Architecture
+`OpenFeature::SDK` (in `lib/open_feature/sdk.rb`) delegates all method calls to `API.instance` via `method_missing`. `API` is a Singleton that holds a `Configuration` object and builds `Client` instances.
 
-Entry point: `require 'open_feature/sdk'` — the `OpenFeature::SDK` module delegates all method calls to `API.instance` (Singleton) via `method_missing`.
+### Provider duck type
 
-### Core Components
+Providers are not subclasses — they follow a duck type interface. Any object implementing `fetch_boolean_value`, `fetch_string_value`, `fetch_number_value`, `fetch_integer_value`, `fetch_float_value`, and `fetch_object_value` (all accepting `flag_key:`, `default_value:`, `evaluation_context:`) works as a provider. Each method must return a `ResolutionDetails` struct. Two built-in providers exist: `NoOpProvider` (default) and `InMemoryProvider` (for testing). Providers may optionally implement `init(evaluation_context)`, `shutdown`, and `metadata`.
 
-- **API** (`lib/open_feature/sdk/api.rb`) — Singleton orchestrator. Manages providers (global or domain-scoped), builds clients, stores API-level evaluation context, and registers event handlers.
-- **Configuration** (`lib/open_feature/sdk/configuration.rb`) — Thread-safe provider storage. Handles provider lifecycle (init/shutdown), domain-scoped provider mapping, and event dispatching. Uses Mutex for all shared state.
-- **Client** (`lib/open_feature/sdk/client.rb`) — Flag evaluation interface. Uses `class_eval` metaprogramming to generate 12 typed methods: `fetch_{boolean,string,number,integer,float,object}_value` and `fetch_*_details` variants. Merges evaluation contexts (API + client + invocation).
-- **EvaluationContext** (`lib/open_feature/sdk/evaluation_context.rb`) — Key-value targeting data with a special `targeting_key`. Supports merging with precedence: invocation > client > API.
+### Client dynamic method generation
 
-### Provider System
+`Client` uses `class_eval` to metaprogram `fetch_<type>_value` and `fetch_<type>_details` methods from `RESULT_TYPE` and `SUFFIXES` arrays. This generates 12 public methods (6 types × 2 suffixes).
 
-- **Provider interface** — Must implement 6 `fetch_*_value` methods, optional `init(evaluation_context)` and `shutdown`. Returns `ResolutionDetails`.
-- **EventEmitter** (`lib/open_feature/sdk/provider/event_emitter.rb`) — Mixin that providers include to emit lifecycle events.
-- **Built-in providers**: `NoOpProvider` (default), `InMemoryProvider` (testing/examples).
-- **Provider states**: `NOT_READY → READY`, with `ERROR`, `FATAL`, `STALE` transitions. Tracked per-instance via `ProviderStateRegistry` using `object_id`.
-- **Initialization modes**: `set_provider` (async, background thread) or `set_provider_and_wait` (sync, raises `ProviderInitializationError` on failure).
+### Evaluation context merging
 
-### Event System
+`EvaluationContextBuilder` merges three layers of context with this precedence: invocation > client > API (global). Context is a hash-like object with a special `targeting_key` field.
 
-- **EventDispatcher** (`lib/open_feature/sdk/event_dispatcher.rb`) — Thread-safe pub-sub. Handlers called outside mutex to prevent deadlocks. Supports API-level and client-level handlers.
-- **ProviderEvent** constants: `PROVIDER_READY`, `PROVIDER_ERROR`, `PROVIDER_STALE`, `PROVIDER_CONFIGURATION_CHANGED`.
+### Provider eventing
 
-## Test Structure
+`Configuration` manages provider lifecycle events (READY, ERROR, STALE, CONFIGURATION_CHANGED). Providers can emit spontaneous events by including `Provider::EventEmitter`. Event handlers can be registered at API level (global) or client level (domain-scoped). `ProviderStateRegistry` tracks provider states; `EventDispatcher` manages handler registration and invocation.
 
-Tests in `spec/` split into two categories:
-- `spec/specification/` — OpenFeature spec compliance tests, organized by requirement number (e.g., "Requirement 1.1.1")
-- `spec/open_feature/` — Unit tests for individual components
+### Domain-based provider binding
 
-Uses Timecop for time-sensitive tests (auto-reset after each test), SimpleCov for coverage.
+Providers can be registered for specific domains. `Configuration#provider(domain:)` resolves domain-specific providers, falling back to the default (nil-domain) provider. Clients are built with an optional `domain:` that binds them to a specific provider.
 
 ## Conventions
 
-- **Linter**: StandardRB (Ruby Standard Style) with `standard-performance` plugin, targeting Ruby 3.1
-- **Commits**: Conventional Commits required for PR titles (enforced by CI)
-- **Releases**: Automated via release-please; changelog auto-generated
-- **Threading**: All shared mutable state must be Mutex-protected. Provider storage uses immutable reassignment (`@providers = @providers.dup.merge(...)`)
-- **Structs for DTOs**: `EvaluationDetails`, `ResolutionDetails`, `ClientMetadata`, `ProviderMetadata` are `Struct`-based
+- All `.rb` files must have `# frozen_string_literal: true` as the first line.
+- Tests live under `spec/` and mirror the `lib/` structure. `spec/specification/` contains tests mapped to OpenFeature spec requirements.
+- Always sign git commits using the `-S` flag.
+- Always include DCO sign-off in commits using the `-s` flag (i.e., `git commit -s -S`). This adds a `Signed-off-by` trailer required by the project's CI.

data/Gemfile.lock

@@ -1,41 +1,51 @@
 PATH
   remote: .
   specs:
-    openfeature-sdk (0.5.1)
+    openfeature-sdk (0.6.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
-    debug (1.9.2)
+    ast (2.4.3)
+    date (3.5.1)
+    debug (1.11.1)
       irb (~> 1.10)
       reline (>= 0.3.8)
-    diff-lcs (1.5.1)
-    docile (1.4.0)
-    io-console (0.7.2)
-    irb (1.12.0)
-      rdoc
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    erb (6.0.2)
+    io-console (0.8.2)
+    irb (1.17.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.7.1)
-    language_server-protocol (3.17.0.3)
+    json (2.18.1)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    markly (0.10.0)
-    parallel (1.24.0)
-    parser (3.3.0.5)
+    markly (0.15.2)
+    parallel (1.27.0)
+    parser (3.3.10.2)
       ast (~> 2.4.1)
       racc
-    psych (5.1.2)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
       stringio
-    racc (1.7.3)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.1.0)
-    rdoc (6.6.3.1)
+    rake (13.3.1)
+    rdoc (7.2.0)
+      erb
       psych (>= 4.0.0)
-    regexp_parser (2.9.0)
-    reline (0.5.0)
+      tsort
+    regexp_parser (2.11.3)
+    reline (0.6.3)
       io-console (~> 0.5)
-    rexml (3.3.6)
-      strscan
+    rexml (3.4.4)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -49,54 +59,59 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.2)
-    rubocop (1.62.1)
+    rubocop (1.84.2)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.2)
-      parser (>= 3.3.0.4)
-    rubocop-performance (1.20.2)
-      rubocop (>= 1.48.1, < 2.0)
-      rubocop-ast (>= 1.30.0, < 2.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-cobertura (2.1.0)
+    simplecov-cobertura (3.1.0)
       rexml
       simplecov (~> 0.19)
-    simplecov-html (0.12.3)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    standard (1.35.1)
+    standard (1.54.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.62.0)
+      rubocop (~> 1.84.0)
       standard-custom (~> 1.0.0)
-      standard-performance (~> 1.3)
+      standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.3.1)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.20.2)
-    stringio (3.1.0)
-    strscan (3.1.0)
+      rubocop-performance (~> 1.26.0)
+    stringio (3.2.0)
     timecop (0.9.10)
-    unicode-display_width (2.5.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-24
+  arm64-darwin-25
   x64-mingw-ucrt
   x64-mingw32
   x86_64-darwin-19
@@ -111,7 +126,7 @@ DEPENDENCIES
   rake (~> 13.0)
   rspec (~> 3.12.0)
   simplecov (~> 0.22.0)
-  simplecov-cobertura (~> 2.1.0)
+  simplecov-cobertura (~> 3.0)
   standard
   standard-performance
   timecop (~> 0.9.10)

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.5.1">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.5.1&color=blue&style=for-the-badge" />
+  <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>
 
   <!-- x-release-please-end -->
@@ -38,9 +38,8 @@
 
 | Supported Ruby Version | OS                    |
 | ------------ | --------------------- |
-| Ruby 3.1.4   | Windows, MacOS, Linux |
-| Ruby 3.2.3   | Windows, MacOS, Linux |
-| Ruby 3.3.0   | Windows, MacOS, Linux |
+| Ruby 3.4.x   | Windows, MacOS, Linux |
+| Ruby 4.0.x   | Windows, MacOS, Linux |
 
 ### Install
 
@@ -101,13 +100,14 @@ 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.                                                                                       |
+| ✅      | [Hooks](#hooks)                                                     | Add functionality to various stages of the flag evaluation life-cycle.                                                                                       |
 | ❌      | [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.                                                                                                  |
+| ✅      | [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) |
-| ⚠️      | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                                          |
+| ✅      | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                                          |
 
 <sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>
 
@@ -201,15 +201,49 @@ bool_value = client.fetch_boolean_value(
 
 ### Hooks
 
-Coming Soon! [Issue available](https://github.com/open-feature/ruby-sdk/issues/52) to be worked on.
-
-<!-- [Hooks](https://openfeature.dev/docs/reference/concepts/hooks) allow for custom logic to be added at well-defined points of the flag evaluation life-cycle.
+[Hooks](https://openfeature.dev/docs/reference/concepts/hooks) allow for custom logic to be added at well-defined points of the flag evaluation life-cycle.
 Look [here](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Hook&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Ruby) for a complete list of available hooks.
 If the hook you're looking for hasn't been created yet, see the [develop a hook](#develop-a-hook) section to learn how to build it yourself.
 
-Once you've added a hook as a dependency, it can be registered at the global, client, or flag invocation level. -->
+Hooks can be registered at the global, client, or flag invocation level.
+
+```ruby
+# Define a hook
+class MyHook
+  include OpenFeature::SDK::Hooks::Hook
+
+  def before(hook_context:, hints:)
+    puts "Evaluating flag: #{hook_context.flag_key}"
+    nil
+  end
+
+  def after(hook_context:, evaluation_details:, hints:)
+    puts "Flag #{hook_context.flag_key} evaluated to: #{evaluation_details.value}"
+  end
+
+  def error(hook_context:, exception:, hints:)
+    puts "Error evaluating #{hook_context.flag_key}: #{exception.message}"
+  end
+
+  def finally(hook_context:, evaluation_details:, hints:)
+    puts "Evaluation complete for #{hook_context.flag_key}"
+  end
+end
+
+# Register at the API (global) level
+OpenFeature::SDK.hooks << MyHook.new
+
+# Register at the client level
+client = OpenFeature::SDK.build_client
+client.hooks << MyHook.new
 
-<!-- TODO: code example of setting hooks at all levels -->
+# Register at the invocation level
+client.fetch_boolean_value(
+  flag_key: "my-flag",
+  default_value: false,
+  hooks: [MyHook.new]
+)
+```
 
 ### Logging
 
@@ -277,19 +311,53 @@ OpenFeature::SDK.remove_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY,
 
 ### Shutdown
 
-Coming Soon! [Issue available](https://github.com/open-feature/ruby-sdk/issues/149) to be worked on.
-
-<!-- TODO The OpenFeature API provides a close function to perform a cleanup of all registered providers.
+The OpenFeature API provides a `shutdown` method to perform cleanup of all registered providers.
 This should only be called when your application is in the process of shutting down.
 
+```ruby
+# Shut down all registered providers and clear state
+OpenFeature::SDK.shutdown
+```
+
+Individual providers can implement a `shutdown` method to perform cleanup:
+
 ```ruby
 class MyProvider
   def shutdown
     # Perform any shutdown/reclamation steps with flag management system here
-    # Return value is ignored
   end
 end
-``` -->
+```
+
+### Tracking
+
+The tracking API allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations.
+This is essential for robust experimentation powered by feature flags.
+For example, a flag enhancing the appearance of a UI component might drive user engagement to a new feature; to test this hypothesis, telemetry collected by a [hook](#hooks) or [provider](#providers) can be associated with telemetry reported in the client's `track` function.
+
+```ruby
+client = OpenFeature::SDK.build_client
+
+# Simple tracking event
+client.track("checkout_completed")
+
+# With evaluation context
+client.track(
+  "purchase",
+  evaluation_context: OpenFeature::SDK::EvaluationContext.new(targeting_key: "user-123")
+)
+
+# With tracking event details (optional numeric value + custom fields)
+details = OpenFeature::SDK::TrackingEventDetails.new(
+  value: 99.99,
+  plan: "premium",
+  currency: "USD"
+)
+client.track("subscription", tracking_event_details: details)
+```
+
+Note that some providers may not support tracking; if the provider does not implement a `track` method, the call is a no-op.
+Check the documentation for your [provider](#providers) for more information.
 
 ### Transaction Context Propagation
 
@@ -345,6 +413,12 @@ class MyProvider
   def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
     # Retrieve a hash value from provider source
   end
+
+  # Optional: implement tracking support (spec 6.1.4)
+  # If not defined, Client#track is a no-op
+  def track(tracking_event_name, evaluation_context:, tracking_event_details:)
+    # Record a tracking event with your flag management system
+  end
 end
 ```
 
@@ -352,17 +426,29 @@ end
 
 ### Develop a hook
 
-Coming Soon! [Issue available](https://github.com/open-feature/ruby-sdk/issues/52) to be worked on.
-
-<!-- To develop a hook, you need to create a new project and include the OpenFeature SDK as a dependency.
+To develop a hook, you need to create a new project and include the OpenFeature SDK as a dependency.
 This can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/ruby-sdk-contrib) available under the OpenFeature organization.
-Implement your own hook by conforming to the `Hook interface`.
-To satisfy the interface, all methods (`Before`/`After`/`Finally`/`Error`) need to be defined.
-To avoid defining empty functions, make use of the `UnimplementedHook` struct (which already implements all the empty functions). -->
+Implement your own hook by including the `OpenFeature::SDK::Hooks::Hook` module.
+You only need to define the stages you care about — unimplemented stages are no-ops by default.
+
+```ruby
+class MyLoggingHook
+  include OpenFeature::SDK::Hooks::Hook
 
-<!-- TODO: code example of hook implementation -->
+  def before(hook_context:, hints:)
+    puts "Evaluating #{hook_context.flag_key}"
+    nil # Return nil or an EvaluationContext to merge
+  end
+
+  def after(hook_context:, evaluation_details:, hints:)
+    puts "Result: #{evaluation_details.value}"
+  end
+
+  # error and finally are optional — only define what you need
+end
+```
 
-<!-- > Built a new hook? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=hook&projects=&template=document-hook.yaml&title=%5BHook%5D%3A+) so we can add it to the docs! -->
+> Built a new hook? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=hook&projects=&template=document-hook.yaml&title=%5BHook%5D%3A+) so we can add it to the docs!
 
 <!-- x-hide-in-docs-start -->
 ## ⭐️ Support the project

data/lib/open_feature/sdk/api.rb

@@ -10,6 +10,7 @@ require_relative "evaluation_details"
 require_relative "client_metadata"
 require_relative "hooks"
 require_relative "client"
+require_relative "tracking_event_details"
 require_relative "provider"
 
 module OpenFeature
@@ -68,6 +69,10 @@ module OpenFeature
       def logger=(new_logger)
         configuration.logger = new_logger
       end
+
+      def shutdown
+        configuration.shutdown
+      end
     end
   end
 end

data/lib/open_feature/sdk/client.rb

@@ -28,6 +28,10 @@ module OpenFeature
         @hooks = []
       end
 
+      def provider_status
+        OpenFeature::SDK.configuration.provider_state(@provider)
+      end
+
       def add_handler(event_type, handler = nil, &block)
         actual_handler = handler || block
         OpenFeature::SDK.configuration.add_client_handler(self, event_type, actual_handler)
@@ -38,6 +42,22 @@ module OpenFeature
         OpenFeature::SDK.configuration.remove_client_handler(self, event_type, actual_handler)
       end
 
+      # Tracking API (spec 6.1.1.1) — dynamic-context paradigm
+      #
+      # Records a tracking event. If the provider does not implement
+      # tracking, this is a no-op (spec 6.1.4).
+      def track(tracking_event_name, evaluation_context: nil, tracking_event_details: nil)
+        return unless @provider.respond_to?(:track)
+
+        built_context = EvaluationContextBuilder.new.call(
+          api_context: OpenFeature::SDK.evaluation_context,
+          client_context: self.evaluation_context,
+          invocation_context: evaluation_context
+        )
+
+        @provider.track(tracking_event_name, evaluation_context: built_context, tracking_event_details: tracking_event_details)
+      end
+
       RESULT_TYPE.each do |result_type|
         SUFFIXES.each do |suffix|
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
@@ -54,6 +74,18 @@ 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 = EvaluationContextBuilder.new.call(
           api_context: OpenFeature::SDK.evaluation_context,
           client_context: self.evaluation_context,
@@ -109,6 +141,13 @@ module OpenFeature
         EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution_details)
       end
 
+      def short_circuit_error_code(state)
+        case state
+        when ProviderState::NOT_READY then Provider::ErrorCode::PROVIDER_NOT_READY
+        when ProviderState::FATAL then Provider::ErrorCode::PROVIDER_FATAL
+        end
+      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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenFeature
   module SDK
     ClientMetadata = Struct.new(:domain, keyword_init: true)

data/lib/open_feature/sdk/configuration.rb

@@ -76,6 +76,26 @@ module OpenFeature
         set_provider_internal(provider, domain: domain, wait_for_init: true)
       end
 
+      def provider_state(provider)
+        @provider_state_registry.get_state(provider)
+      end
+
+      def provider_tracked?(provider)
+        @provider_state_registry.tracked?(provider)
+      end
+
+      def shutdown
+        providers_to_shutdown = @provider_mutex.synchronize { @providers.values.uniq }
+
+        providers_to_shutdown.each do |prov|
+          prov.shutdown if prov.respond_to?(:shutdown)
+        rescue => e
+          @logger&.warn("Error shutting down provider #{prov&.class&.name || "unknown"}: #{e.message}")
+        end
+
+        reset
+      end
+
       private
 
       def reset
@@ -171,10 +191,6 @@ module OpenFeature
         run_handlers_for_provider(provider, event_type, event_details)
       end
 
-      def provider_state(provider)
-        @provider_state_registry.get_state(provider)
-      end
-
       private
 
       def extract_provider_name(provider)
@@ -219,8 +235,7 @@ module OpenFeature
             provider_state = @provider_state_registry.get_state(provider)
 
             if event_type == status_to_event[provider_state]
-              provider_name = extract_provider_name(provider)
-              event_details = {provider_name: provider_name}
+              event_details = build_event_details(provider)
 
               begin
                 handler.call(event_details)
@@ -237,8 +252,7 @@ module OpenFeature
           provider_state = @provider_state_registry.get_state(client_provider)
 
           if event_type == status_to_event[provider_state]
-            provider_name = extract_provider_name(client_provider)
-            event_details = {provider_name: provider_name}
+            event_details = build_event_details(client_provider)
 
             begin
               handler.call(event_details)
@@ -248,6 +262,11 @@ module OpenFeature
           end
         end
       end
+
+      def build_event_details(provider)
+        stored_details = @provider_state_registry.get_details(provider)
+        {provider_name: extract_provider_name(provider)}.merge(stored_details)
+      end
     end
   end
 end

data/lib/open_feature/sdk/evaluation_context.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenFeature
   module SDK
     class EvaluationContext

data/lib/open_feature/sdk/evaluation_context_builder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenFeature
   module SDK
     # Used to combine evaluation contexts from different sources

data/lib/open_feature/sdk/evaluation_details.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenFeature
   module SDK
     EvaluationDetails = Struct.new(:flag_key, :resolution_details, keyword_init: true) do

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

@@ -22,6 +22,14 @@ module OpenFeature
           @evaluation_context = evaluation_context
           @client_metadata = client_metadata
           @provider_metadata = provider_metadata
+          @hook_data = {}
+        end
+
+        # Returns a mutable hash scoped to the given hook instance.
+        # The same hash is returned across all hook stages (before, after, error, finally),
+        # allowing hooks to share state across their lifecycle (spec 4.1.5, 4.6.1).
+        def hook_data_for(hook)
+          @hook_data[hook.object_id] ||= {}
         end
       end
     end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenFeature
   module SDK
     module Provider

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

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+
 module OpenFeature
   module SDK
     module Provider
-      # TODO: Add evaluation context support
       class InMemoryProvider
+        include Provider::EventEmitter
+
         NAME = "In-memory Provider"
 
         attr_reader :metadata
@@ -22,7 +25,12 @@ module OpenFeature
 
         def add_flag(flag_key:, value:)
           flags[flag_key] = value
-          # TODO: Emit PROVIDER_CONFIGURATION_CHANGED event once events are implemented
+          emit_provider_changed([flag_key])
+        end
+
+        def update_flags(new_flags)
+          @flags = new_flags.dup
+          emit_provider_changed(new_flags.keys)
         end
 
         def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
@@ -54,13 +62,24 @@ module OpenFeature
         attr_reader :flags
 
         def fetch_value(flag_key:, default_value:, evaluation_context:)
-          value = flags[flag_key]
+          raw_value = flags[flag_key]
 
-          if value.nil?
+          if raw_value.nil?
             return ResolutionDetails.new(value: default_value, error_code: ErrorCode::FLAG_NOT_FOUND, reason: Reason::ERROR)
           end
 
-          ResolutionDetails.new(value:, reason: Reason::STATIC)
+          if raw_value.respond_to?(:call)
+            value = raw_value.call(evaluation_context)
+            ResolutionDetails.new(value: value, reason: Reason::TARGETING_MATCH)
+          else
+            ResolutionDetails.new(value: raw_value, reason: Reason::STATIC)
+          end
+        end
+
+        def emit_provider_changed(flag_keys)
+          return unless configuration_attached?
+
+          emit_event(ProviderEvent::PROVIDER_CONFIGURATION_CHANGED, flags_changed: flag_keys)
         end
       end
     end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenFeature
   module SDK
     module Provider

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenFeature
   module SDK
     module Provider

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

@@ -1,7 +1,22 @@
+# frozen_string_literal: true
+
 module OpenFeature
   module SDK
     module Provider
-      ResolutionDetails = Struct.new(:value, :reason, :variant, :error_code, :error_message, :flag_metadata, keyword_init: true)
+      EMPTY_FLAG_METADATA = {}.freeze
+
+      ResolutionDetails = Struct.new(:value, :reason, :variant, :error_code, :error_message, :flag_metadata, keyword_init: true) do
+        def flag_metadata
+          raw = self[:flag_metadata]
+          if raw.nil?
+            EMPTY_FLAG_METADATA
+          elsif raw.frozen?
+            raw
+          else
+            raw.dup.freeze
+          end
+        end
+      end
     end
   end
 end

data/lib/open_feature/sdk/provider.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "provider/error_code"
 require_relative "provider/reason"
 require_relative "provider/resolution_details"

data/lib/open_feature/sdk/provider_state_registry.rb

@@ -17,7 +17,7 @@ module OpenFeature
         return unless provider
 
         @mutex.synchronize do
-          @states[provider.object_id] = state
+          @states[provider.object_id] = {state: state, details: {}}
         end
       end
 
@@ -29,7 +29,7 @@ module OpenFeature
         # Only update state if the event should cause a state change
         if new_state
           @mutex.synchronize do
-            @states[provider.object_id] = new_state
+            @states[provider.object_id] = {state: new_state, details: event_details || {}}
           end
           new_state
         else
@@ -42,7 +42,17 @@ module OpenFeature
         return ProviderState::NOT_READY unless provider
 
         @mutex.synchronize do
-          @states[provider.object_id] || ProviderState::NOT_READY
+          entry = @states[provider.object_id]
+          entry ? entry[:state] : ProviderState::NOT_READY
+        end
+      end
+
+      def get_details(provider)
+        return {} unless provider
+
+        @mutex.synchronize do
+          entry = @states[provider.object_id]
+          entry ? entry[:details] : {}
         end
       end
 
@@ -54,6 +64,14 @@ module OpenFeature
         end
       end
 
+      def tracked?(provider)
+        return false unless provider
+
+        @mutex.synchronize do
+          @states.key?(provider.object_id)
+        end
+      end
+
       def ready?(provider)
         get_state(provider) == ProviderState::READY
       end

data/lib/open_feature/sdk/tracking_event_details.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    # Represents tracking event details per spec section 6.2.
+    #
+    # Requirement 6.2.1: MUST define an optional numeric value.
+    # Requirement 6.2.2: MUST support custom fields (string keys,
+    # boolean/string/number/structure values).
+    class TrackingEventDetails
+      attr_reader :value, :fields
+
+      def initialize(value: nil, **fields)
+        if !value.nil? && !value.is_a?(Numeric)
+          raise ArgumentError, "Tracking event value must be Numeric, got #{value.class}"
+        end
+
+        @value = value
+        @fields = fields.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openfeature-sdk
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - OpenFeature Authors
@@ -113,14 +113,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement
@@ -185,6 +185,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/tracking_event_details.rb
 - lib/open_feature/sdk/version.rb
 - release-please-config.json
 - renovate.json
@@ -204,14 +205,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: OpenFeature SDK for Ruby
 test_files: []