PR fixes and small improvements

Signed-off-by: Max Pinheiro <max.pinheiro@fluxon.com>

Author: maxnrp

kotlin-sdk/api/android/kotlin-sdk.api

@@ -407,7 +407,8 @@ public final class dev/openfeature/kotlin/sdk/ProviderStatusTracker {
 	public fun <init> ()V
 	public final fun getStatus ()Lkotlinx/coroutines/flow/StateFlow;
 	public final fun observe ()Lkotlinx/coroutines/flow/Flow;
-	public final fun send (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents;)V
+	public final fun send (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents;Ldev/openfeature/kotlin/sdk/OpenFeatureStatus;)V
+	public static synthetic fun send$default (Ldev/openfeature/kotlin/sdk/ProviderStatusTracker;Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents;Ldev/openfeature/kotlin/sdk/OpenFeatureStatus;ILjava/lang/Object;)V
 }
 
 public final class dev/openfeature/kotlin/sdk/Reason : java/lang/Enum {
@@ -750,15 +751,6 @@ public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$P
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderNotReady : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
-	public static final field INSTANCE Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderNotReady;
-	public fun equals (Ljava/lang/Object;)Z
-	public synthetic fun getEventDetails ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
-	public fun getEventDetails ()Ljava/lang/Void;
-	public fun hashCode ()I
-	public fun toString ()Ljava/lang/String;
-}
-
 public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReady : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
 	public fun <init> ()V
 	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)V

kotlin-sdk/api/jvm/kotlin-sdk.api

@@ -407,7 +407,8 @@ public final class dev/openfeature/kotlin/sdk/ProviderStatusTracker {
 	public fun <init> ()V
 	public final fun getStatus ()Lkotlinx/coroutines/flow/StateFlow;
 	public final fun observe ()Lkotlinx/coroutines/flow/Flow;
-	public final fun send (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents;)V
+	public final fun send (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents;Ldev/openfeature/kotlin/sdk/OpenFeatureStatus;)V
+	public static synthetic fun send$default (Ldev/openfeature/kotlin/sdk/ProviderStatusTracker;Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents;Ldev/openfeature/kotlin/sdk/OpenFeatureStatus;ILjava/lang/Object;)V
 }
 
 public final class dev/openfeature/kotlin/sdk/Reason : java/lang/Enum {
@@ -750,15 +751,6 @@ public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$P
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderNotReady : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
-	public static final field INSTANCE Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderNotReady;
-	public fun equals (Ljava/lang/Object;)Z
-	public synthetic fun getEventDetails ()Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;
-	public fun getEventDetails ()Ljava/lang/Void;
-	public fun hashCode ()I
-	public fun toString ()Ljava/lang/String;
-}
-
 public final class dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$ProviderReady : dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents {
 	public fun <init> ()V
 	public fun <init> (Ldev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents$EventDetails;)V

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/FeatureProvider.kt

@@ -4,8 +4,23 @@ import dev.openfeature.kotlin.sdk.events.OpenFeatureProviderEvents
 import dev.openfeature.kotlin.sdk.exceptions.OpenFeatureError
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.emptyFlow
+import kotlin.DeprecationLevel
+import kotlin.ReplaceWith
 import kotlin.coroutines.cancellation.CancellationException
 
+/**
+ * Flag evaluation entry point for a feature flag backend.
+ *
+ * Plain implementations remain supported; the SDK may wrap them when registered.
+ */
+@Deprecated(
+    message = "Implement StateManagingProvider for integrated lifecycle status and provider events.",
+    replaceWith = ReplaceWith(
+        expression = "StateManagingProvider",
+        imports = ["dev.openfeature.kotlin.sdk.StateManagingProvider"]
+    ),
+    level = DeprecationLevel.WARNING
+)
 interface FeatureProvider {
     val hooks: List<Hook<*>>
     val metadata: ProviderMetadata

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/LegacyFeatureProviderAdapter.kt

@@ -2,6 +2,7 @@ package dev.openfeature.kotlin.sdk
 
 import dev.openfeature.kotlin.sdk.events.OpenFeatureProviderEvents
 import dev.openfeature.kotlin.sdk.events.toOpenFeatureStatus
+import dev.openfeature.kotlin.sdk.exceptions.ErrorCode
 import dev.openfeature.kotlin.sdk.exceptions.OpenFeatureError
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineDispatcher
@@ -10,9 +11,12 @@ import kotlinx.coroutines.Job
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asSharedFlow
 import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.collect
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.yield
 
@@ -33,18 +37,20 @@ internal class LegacyFeatureProviderAdapter(
 
     private val _status = MutableStateFlow<OpenFeatureStatus>(OpenFeatureStatus.NotReady)
     override val status: StateFlow<OpenFeatureStatus> = _status.asStateFlow()
+    private val eventFlow = MutableSharedFlow<OpenFeatureProviderEvents>(replay = 1, extraBufferCapacity = 5)
 
     private val scope = CoroutineScope(SupervisorJob() + eventDispatcher)
     private var observeJob: Job? = null
 
-    override fun observe(): Flow<OpenFeatureProviderEvents> = inner.observe()
+    override fun observe(): Flow<OpenFeatureProviderEvents> = eventFlow.asSharedFlow()
 
     override suspend fun initialize(initialContext: EvaluationContext?) {
         observeJob?.cancel(CancellationException("Provider job was cancelled due to new provider"))
         _status.value = OpenFeatureStatus.NotReady
         observeJob = scope.launch {
             inner.observe().collect { event ->
                 event.toOpenFeatureStatus()?.let { _status.value = it }
+                eventFlow.emit(event)
             }
         }
         try {
@@ -56,20 +62,30 @@ internal class LegacyFeatureProviderAdapter(
     }
 
     /**
-     * [inner] is shut down first while the [observeJob] is still running so a provider can emit
-     * a final [OpenFeatureProviderEvents] on [FeatureProvider.observe] and this adapter can still
-     * apply [toOpenFeatureStatus] to [_status]. The observe job and [scope] (including
-     * [SupervisorJob]) are cancelled in [finally] so cleanup and resource release always run.
+     * Releases the adapter and underlying provider; updates [status] and [observe] per
+     * [StateManagingProvider.shutdown], then tears down coroutine resources.
      */
     override fun shutdown() {
         try {
-            inner.shutdown()
+            observeJob?.cancel(
+                CancellationException("Provider event observe job was cancelled due to shutdown")
+            )
+            observeJob = null
+
             _status.value = OpenFeatureStatus.NotReady
+            eventFlow.tryEmit(
+                OpenFeatureProviderEvents.ProviderError(
+                    OpenFeatureProviderEvents.EventDetails(
+                        message = "Provider shut down; not ready for evaluation",
+                        errorCode = ErrorCode.PROVIDER_NOT_READY
+                    )
+                )
+            )
+
+            inner.shutdown()
         } catch (e: Throwable) {
             handleError(e)
         } finally {
-            observeJob?.cancel(CancellationException("Provider event observe job was cancelled due to shutdown"))
-            observeJob = null
             scope.cancel(
                 CancellationException("LegacyFeatureProviderAdapter scope cancelled due to shutdown")
             )

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/ProviderStatusTracker.kt

@@ -13,8 +13,9 @@ import kotlinx.coroutines.flow.asStateFlow
 
 /**
  * Single place for [OpenFeatureStatus] and the provider event stream: call [send] for each lifecycle
- * step; [status] is derived with the same [toOpenFeatureStatus] rules as the rest of the SDK. Do not
- * set readiness from another [StateFlow] outside [send]. For [StateManagingProvider], expose
+ * step. By default [status] is updated from [event] using [toOpenFeatureStatus]. Pass an explicit
+ * [statusUpdate] when the snapshot differs (for example aggregated status in a multi-provider).
+ * Do not set readiness from another [StateFlow] outside [send]. For [StateManagingProvider], expose
  * [status] and [observe] from the tracker, or use [OpenFeatureAPI.statusFlow] for readiness if registered.
  *
  * [observe] uses a [MutableSharedFlow] with `replay = 1`. New subscribers replay the
@@ -31,9 +32,12 @@ class ProviderStatusTracker {
 
     val status: StateFlow<OpenFeatureStatus> = _status.asStateFlow()
 
-    fun send(event: OpenFeatureProviderEvents) {
+    fun send(
+        event: OpenFeatureProviderEvents,
+        statusUpdate: OpenFeatureStatus? = event.toOpenFeatureStatus()
+    ) {
         synchronized(providerMutex) {
-            event.toOpenFeatureStatus()?.let { _status.value = it }
+            statusUpdate?.let { _status.value = it }
             _events.tryEmit(event)
         }
     }

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/StateManagingProvider.kt

@@ -1,6 +1,7 @@
 package dev.openfeature.kotlin.sdk
 
 import dev.openfeature.kotlin.sdk.events.OpenFeatureProviderEvents
+import dev.openfeature.kotlin.sdk.exceptions.ErrorCode
 import dev.openfeature.kotlin.sdk.exceptions.OpenFeatureError
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.StateFlow
@@ -10,8 +11,7 @@ import kotlin.coroutines.cancellation.CancellationException
  * Provider that owns lifecycle [OpenFeatureStatus] in [status] and reports changes on [observe].
  *
  * Implementations must update [status] first, then emit on [observe], so readers of either see a
- * consistent order. Plain [FeatureProvider] implementations are wrapped internally; their status is
- * derived from [observe] via an SDK adapter.
+ * consistent order.
  */
 interface StateManagingProvider : FeatureProvider {
     /**
@@ -39,7 +39,8 @@ interface StateManagingProvider : FeatureProvider {
      * Called when the client lifecycle ends; release resources and threads.
      *
      * Before returning: set [status] to [OpenFeatureStatus.NotReady], then emit
-     * [OpenFeatureProviderEvents.ProviderError] on [observe].
+     * [OpenFeatureProviderEvents.ProviderError] on [observe] with [ErrorCode.PROVIDER_NOT_READY] in
+     * [OpenFeatureProviderEvents.EventDetails.errorCode].
      */
     override fun shutdown()
 
@@ -58,12 +59,11 @@ interface StateManagingProvider : FeatureProvider {
     override suspend fun onContextSet(oldContext: EvaluationContext?, newContext: EvaluationContext)
 
     /**
-     * Provider lifecycle events. Replace [FeatureProvider.observe]'s empty default.
+     * Lifecycle and provider events for this instance.
      *
-     * Implementations update [status] before each matching emission. For [initialize], set [status]
-     * first, then emit [OpenFeatureProviderEvents.ProviderReady] or
-     * [OpenFeatureProviderEvents.ProviderError], or the SDK remains [OpenFeatureStatus.NotReady]. Other
-     * events surface through [OpenFeatureAPI.observe].
+     * For each step, update [status] first, then emit the matching [OpenFeatureProviderEvents] on this
+     * flow; required pairings for [initialize], [shutdown], and [onContextSet] are described on those
+     * methods.
      */
     override fun observe(): Flow<OpenFeatureProviderEvents>
 }

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/events/OpenFeatureProviderEvents.kt

@@ -52,38 +52,27 @@ sealed class OpenFeatureProviderEvents {
     data class ProviderReconciling(
         override val eventDetails: EventDetails? = null
     ) : OpenFeatureProviderEvents()
-
-    @Deprecated("Use ProviderError instead", ReplaceWith("ProviderError"))
-    data object ProviderNotReady : OpenFeatureProviderEvents() {
-        override val eventDetails = null
-    }
 }
 
 /**
- * Maps lifecycle events to [OpenFeatureStatus], or null when the event does not change readiness
- * (for example [OpenFeatureProviderEvents.ProviderConfigurationChanged]).
+ * Derives the [OpenFeatureStatus] implied by this event for status aggregation and tracking, if any.
  *
- * [OpenFeatureProviderEvents.ProviderError] with [ErrorCode.PROVIDER_NOT_READY] matches the deprecated
- * [OpenFeatureProviderEvents.ProviderNotReady] object: both map to [OpenFeatureStatus.NotReady] for
- * aggregation and status derivation.
+ * Returns `null` when the event does not represent a status transition from the SDK's perspective.
  */
 internal fun OpenFeatureProviderEvents.toOpenFeatureStatus(): OpenFeatureStatus? = when (this) {
     is OpenFeatureProviderEvents.ProviderReady -> OpenFeatureStatus.Ready
-    is OpenFeatureProviderEvents.ProviderNotReady -> OpenFeatureStatus.NotReady
     is OpenFeatureProviderEvents.ProviderReconciling -> OpenFeatureStatus.Reconciling
     is OpenFeatureProviderEvents.ProviderStale -> OpenFeatureStatus.Stale
-    is OpenFeatureProviderEvents.ProviderError -> when (eventDetails?.errorCode) {
-        ErrorCode.PROVIDER_NOT_READY -> OpenFeatureStatus.NotReady
-        else -> toOpenFeatureStatusError()
-    }
     is OpenFeatureProviderEvents.ProviderConfigurationChanged -> null
+    is OpenFeatureProviderEvents.ProviderError -> toOpenFeatureStatusError()
     else -> null
 }
 
 internal fun OpenFeatureProviderEvents.ProviderError.toOpenFeatureStatusError(): OpenFeatureStatus {
     val code = eventDetails?.errorCode ?: return OpenFeatureStatus.Error(
         OpenFeatureError.GeneralError(eventDetails?.message ?: "Unspecified error")
     )
+    if (code == ErrorCode.PROVIDER_NOT_READY) return OpenFeatureStatus.NotReady
     val openFeatureError = OpenFeatureError.fromMessageAndErrorCode(
         errorMessage = eventDetails.message ?: "Provider did not supply an error message",
         errorCode = code

kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/multiprovider/MultiProvider.kt

@@ -6,6 +6,7 @@ import dev.openfeature.kotlin.sdk.Hook
 import dev.openfeature.kotlin.sdk.OpenFeatureStatus
 import dev.openfeature.kotlin.sdk.ProviderEvaluation
 import dev.openfeature.kotlin.sdk.ProviderMetadata
+import dev.openfeature.kotlin.sdk.ProviderStatusTracker
 import dev.openfeature.kotlin.sdk.StateManagingProvider
 import dev.openfeature.kotlin.sdk.TrackingEventDetails
 import dev.openfeature.kotlin.sdk.Value
@@ -21,14 +22,9 @@ import kotlinx.coroutines.async
 import kotlinx.coroutines.awaitAll
 import kotlinx.coroutines.coroutineScope
 import kotlinx.coroutines.flow.Flow
-import kotlinx.coroutines.flow.MutableSharedFlow
-import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
-import kotlinx.coroutines.flow.asSharedFlow
-import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.launchIn
 import kotlinx.coroutines.flow.onEach
-import kotlinx.coroutines.flow.update
 import kotlinx.coroutines.launch
 
 /**
@@ -128,15 +124,13 @@ class MultiProvider(
         }
     }
 
-    private val _statusFlow = MutableStateFlow<OpenFeatureStatus>(OpenFeatureStatus.NotReady)
+    private val statusTracker = ProviderStatusTracker()
 
-    override val status: StateFlow<OpenFeatureStatus> = _statusFlow.asStateFlow()
+    override val status: StateFlow<OpenFeatureStatus> = statusTracker.status
 
     // Legacy path: Add getter to return the status as statusFlow, an alias for backwards compatibility
     val statusFlow get() = status
 
-    private val eventFlow = MutableSharedFlow<OpenFeatureProviderEvents>(replay = 1, extraBufferCapacity = 5)
-
     // Track individual provider statuses, initial state of all providers is NotReady
     private val childProviderStatuses: MutableMap<ChildFeatureProvider, OpenFeatureStatus> =
         childFeatureProviders.associateWithTo(mutableMapOf()) { OpenFeatureStatus.NotReady }
@@ -174,7 +168,7 @@ class MultiProvider(
      */
     internal fun getProviderCount(): Int = childFeatureProviders.size
 
-    override fun observe(): Flow<OpenFeatureProviderEvents> = eventFlow.asSharedFlow()
+    override fun observe(): Flow<OpenFeatureProviderEvents> = statusTracker.observe()
 
     /**
      * Initializes all underlying providers with the given context.
@@ -208,23 +202,19 @@ class MultiProvider(
         }
     }
 
-    private suspend fun handleProviderEvent(provider: ChildFeatureProvider, event: OpenFeatureProviderEvents) {
-        if (event is OpenFeatureProviderEvents.ProviderConfigurationChanged) {
-            // Configuration-only: forward to observers; aggregate readiness is unchanged.
-            eventFlow.emit(event)
+    private fun handleProviderEvent(provider: ChildFeatureProvider, event: OpenFeatureProviderEvents) {
+        val newChildStatus = event.toOpenFeatureStatus()
+        if (newChildStatus == null) {
+            statusTracker.send(event)
             return
         }
 
-        val newChildStatus = event.toOpenFeatureStatus() ?: return
-
-        val previousStatus = _statusFlow.value
+        val previousStatus = statusTracker.status.value
         childProviderStatuses[provider] = newChildStatus
         val newStatus = calculateAggregateStatus()
 
         if (previousStatus != newStatus) {
-            _statusFlow.update { newStatus }
-            // Re-emit the original event that triggered the aggregate status change
-            eventFlow.emit(event)
+            statusTracker.send(event, statusUpdate = newStatus)
         }
     }
 
@@ -242,6 +232,15 @@ class MultiProvider(
             cause = CancellationException("Observe provider events job cancelled due to shutdown")
         )
 
+        statusTracker.send(
+            OpenFeatureProviderEvents.ProviderError(
+                OpenFeatureProviderEvents.EventDetails(
+                    message = "MultiProvider shut down; not ready for evaluation",
+                    errorCode = ErrorCode.PROVIDER_NOT_READY
+                )
+            )
+        )
+
         val shutdownErrors = mutableListOf<Pair<String, Throwable>>()
         childFeatureProviders.forEach { provider ->
             try {
@@ -267,15 +266,6 @@ class MultiProvider(
             }
             throw aggregate
         }
-        _statusFlow.value = OpenFeatureStatus.NotReady
-        eventFlow.tryEmit(
-            OpenFeatureProviderEvents.ProviderError(
-                OpenFeatureProviderEvents.EventDetails(
-                    message = "MultiProvider shut down; not ready for evaluation",
-                    errorCode = ErrorCode.PROVIDER_NOT_READY
-                )
-            )
-        )
     }
 
     override suspend fun onContextSet(