feat!: Add SMP + Legacy Provider adaptor

[maxnrp]

Intent

Address the race condition in the current SDK implementation, where lifecycle state is split between the provider and the API, causing undefined event ordering in concurrent scenarios.

This is achieved by narrowing event emission to a single source of truth — the provider itself — via the status: StateFlow<OpenFeatureStatus> property on StateManagingProvider, eliminating the window between initialize() returning and the API updating its internal state. State transitions are the authoritative origin of events, which are emitted in response to each lifecycle stage change.

Introduce a small helper for StateManagingProvider implementations, the ProviderStatusTracker: one place to drive OpenFeatureStatus and the provider event stream with the same event → status rules as the rest of the SDK.

Motivation

open-feature/spec#365 — Provider lifecycle race condition in multi-threaded SDKs
The issue above describes how split ownership of state and events between the API and the provider can produce undefined ordering under concurrency (e.g. API publishing “ready” while the provider emits something else from background work when it actually finishes initializing).

This change aligns the Kotlin SDK with the direction there: the provider is the party that can own a single, authoritative OpenFeatureStatus stream. The API forwards it instead of racing to update the same conceptual state after initialize for implementations. That does not rewrite the whole spec, but it reduces split ownership for the new path while preserving the old behavior for legacy providers.

Providers that only implement FeatureProvider (and not StateManagingProvider) are automatically wrapped by LegacyFeatureProviderAdapter at registration time. The adapter derives status from the provider's observe() events — preserving all existing behavior including status buffering, Ready/Error handling around initialize() and onContextSet(), and event mirroring — while making the provider fully StateManagingProvider-compliant internally. This wrapping is transparent: getProvider() always returns the original provider instance.

Changes

• Introduced StateManagingProvider as an extension of FeatureProvider, exposing status: StateFlow<OpenFeatureStatus> as the single source of truth for lifecycle state.
• Introduced LegacyFeatureProviderAdapter, an internal adapter that wraps plain FeatureProvider implementations, deriving their status from observe() events and preserving legacy lifecycle semantics.
• OpenFeatureAPI now:
  Delegates getStatus() and statusFlow directly to the active provider's status: StateFlow.
  Normalizes all registered providers to StateManagingProvider at registration time — either directly if already implementing it, or via LegacyFeatureProviderAdapter.
  Updates setProvider and setProviderAndWait to suspend until the provider emits a state other than NotReady after initialize() completes.
  getProvider() unwraps LegacyFeatureProviderAdapter to always return the original registered provider.
• NoOpProvider and MultiProvider implement StateManagingProvider.
• ProviderStatusTracker updates derived StateFlow via toOpenFeatureStatus() and broadcasts with tryEmit on a MutableSharedFlow.

Tests

StateManagingProviderStatusTests — Legacy init, observe mirrored into SDK status via LegacyFeatureProviderAdapter, onContextSet, getStatus from provider status, provider replacement/shutdown.

LegacyFeatureProviderStatusTests — Legacy init, observe mirrored into SDK status, onContextSet, getStatus from SDK buffer, provider replacement/shutdown.

StatusTests — End-to-end transitions, clear/shutdown, concurrent context updates with a state-managing slow provider, provider replacement (including async setProvider).

MultiProviderTests — Existing multi-provider behavior (strategies, lifecycle, track, error aggregation, init with long-running flows).

ProviderStatusTrackerTest — send → status mapping, replay + subsequent sends, not-ready/timeout, two collectors, ProviderConfigurationChanged not changing status, error details preserved under replay, etc.

Together, these unite legacy and state-managing behavior and cover init, status, and context and shutdown, under concurrency where relevant.

Breaking changes vs legacy compliance

• Intended backward compatible.
• StateManagingProvider (standard for custom providers)
• LegacyFeatureProviderAdapter (internal — not part of public API)
• API update: new public type: StateManagingProvider

Dependency

This change requires a follow-up merge in: open-feature/kotlin-sdk-contrib

• PR: chore: Update FeatureProvider to SMP kotlin-sdk-contrib#35

[gemini-code-assist]

Code Review

This pull request introduces the StateManagingProvider interface, which allows providers to manage their own lifecycle status via a StateFlow. The OpenFeatureAPI has been refactored to derive the SDK's overall status from the active provider, and a LegacyFeatureProviderAdapter was added to wrap existing FeatureProvider implementations, which are now deprecated. Feedback was provided regarding a redundant status check in the legacy adapter's initialization logic.

[toddbaert]

Related spec PR: open-feature/spec#367