Spec compliance roadmap: bring ruby-sdk up to latest OpenFeature specification

[josecolella]

Summary

A gap analysis of the OpenFeature Ruby SDK (v0.5.1) against the latest OpenFeature specification reveals several areas where the SDK does not yet fully comply. This issue serves as the coordination point for bringing the ruby-sdk to full spec compliance, organized into three phases by priority.

---

Phase 1 — Stable / MUST Requirements ✅ COMPLETE

All MUST-level requirements from stable sections of the spec are now addressed.

• Shutdown / Close API (spec 1.6.1, 1.6.2) — Implemented in feat: add shutdown API, provider status, and status short-circuit #223. See Enable shutdown to be invoked from API layer #149
• Provider Status on Client (spec 1.7.1) — Implemented in feat: add shutdown API, provider status, and status short-circuit #223
• Provider Status Short-Circuit (spec 1.7.6, 1.7.7) — Implemented in feat: add shutdown API, provider status, and status short-circuit #223
• Hook Data (per-hook mutable state) (spec 4.1.1, 4.1.5, 4.3.2, 4.6.1) — Implemented in feat: add hook data per-hook mutable state #222
• Flag Metadata Defaulting / Immutability (spec 1.4.14, 1.4.15.1) — Implemented in feat: add flag metadata defaulting and immutability #221
• Evaluation Details in finally hook (spec 4.3.8) — Verified & tested in feat: add hook data per-hook mutable state #222. See Add evaluation details to finally hook stage #175
• Event Details payload (spec 5.1.4, 5.1.5) — Implemented in feat: populate event details payload with error_code and message #225. Closes Implement event details #210

Phase 2 — Hardening / SHOULD + InMemoryProvider

These are SHOULD-level requirements or enhancements to built-in providers that improve SDK robustness.

• InMemoryProvider context callbacks (Appendix A) — Implemented in feat: add InMemoryProvider context callbacks and event emission #224
• InMemoryProvider flag set update + events (Appendix A) — Implemented in feat: add InMemoryProvider context callbacks and event emission #224
• Logging capabilities (spec 1.4.11, Appendix A) — No logging hook or structured logging integration. See Add logging capabilities #148
• OpenTelemetry telemetry hook (Appendix D) — Not implemented. See Add OpenTelemetry-Compatible Telemetry Utility Function #176
• Multi-Provider (Appendix A) — Not implemented. See Multi-Provider support #212

Phase 3 — Experimental Features

• Tracking API (spec 6.1.1.1, 6.1.3, 6.1.4, 6.2) — Implemented in feat: implement Tracking API (spec section 6) #227. Closes [FEATURE] Implement Tracking in Ruby #157
• Transaction Context Propagation (spec 3.3.1.1, 3.3.1.2) — Not implemented. See Enable transaction context propogation #150

---

Progress

Phase	Done	Remaining
Phase 1 (MUST)	7/7 ✅	—
Phase 2 (SHOULD)	2/5	Logging, OTel, Multi-Provider
Phase 3 (Experimental)	1/2	Transaction Context

Merged PRs

• feat: add flag metadata defaulting and immutability #221 — Flag metadata defaulting + immutability (spec 1.4.14, 1.4.15.1)
• feat: add hook data per-hook mutable state #222 — Hook data per-hook state + finally details tests (spec 4.1.5, 4.3.8)
• feat: add shutdown API, provider status, and status short-circuit #223 — Shutdown API, provider status, status short-circuit (spec 1.6, 1.7)
• feat: add InMemoryProvider context callbacks and event emission #224 — InMemoryProvider context callbacks + event emission (Appendix A)
• feat: populate event details payload with error_code and message #225 — Event details payload with error_code and message (spec 5.1.4, 5.1.5)
• feat: implement Tracking API (spec section 6) #227 — Tracking API (spec section 6)
• docs: update README with hooks, shutdown, tracking, and hook development #228 — README update reflecting all completed work

---

Remaining Work

Phase 2

• Logging (Add logging capabilities #148) — Add a logging hook or structured logging integration. The SDK already has a logger accessor on Configuration.
• OpenTelemetry hook (Add OpenTelemetry-Compatible Telemetry Utility Function #176) — Should be a separate gem (openfeature-sdk-otel). Not core SDK work.
• Multi-Provider (Multi-Provider support #212) — Composite provider pattern. Significant design work — typically a separate gem.

Phase 3

• Transaction Context Propagation (Enable transaction context propogation #150) — Thread/fiber-local context storage. Touches the context merging pipeline.

---

Already Compliant

Area	Spec Sections
API Initialization	1.1 — singleton, provider mutation, domains, hooks, metadata, client creation
Client flag evaluation	1.2, 1.3 — 6 types × 2 suffixes, dynamic-context paradigm
Detailed evaluation	1.4 — EvaluationDetails with value, variant, reason, error_code, error_message, flag_metadata (with defaulting + immutability)
Provider duck type	2.1–2.5 — init, shutdown, metadata, NoOpProvider, InMemoryProvider
Evaluation Context	3.1, 3.2 — targeting_key, custom fields, 3-level merging
Hooks lifecycle	4.1–4.5 — before/after/error/finally, ordering, context mutation, hints, hook_data
Events	5.1–5.3 — 4 event types, 5 provider states, API+client handlers, handler removal, event details
Tracking	6.1–6.2 — Client#track, context merging, TrackingEventDetails, no-op for non-tracking providers
Shutdown	1.6 — API-level shutdown propagation to all providers
Provider Status	1.7 — Client provider_status accessor, NOT_READY/FATAL short-circuit
Error codes	8 defined
Reasons	9 defined

---

Key Files

File	Purpose
lib/open_feature/sdk/api.rb	API singleton — shutdown, provider registration
lib/open_feature/sdk/client.rb	Client — evaluation, hooks, provider status, tracking
lib/open_feature/sdk/configuration.rb	Provider lifecycle, events
lib/open_feature/sdk/hooks/hook_executor.rb	Hook execution engine
lib/open_feature/sdk/hooks/hook_context.rb	Hook context with hook_data support
lib/open_feature/sdk/tracking_event_details.rb	Tracking event details (value + custom fields)
lib/open_feature/sdk/provider/in_memory_provider.rb	Built-in test provider with context callbacks + events
lib/open_feature/sdk/provider/event_emitter.rb	Provider event support
lib/open_feature/sdk/provider_state_registry.rb	Provider state + event details tracking
spec/specification/	Spec-mapped compliance tests

---

🤖 Jose's AI agent