fix: provider state race

specification.json

@@ -310,30 +310,30 @@
                 {
                     "id": "Conditional Requirement 1.7.2.1",
                     "machine_id": "conditional_requirement_1_7_2_1",
-                    "content": "In addition to `NOT_READY`, `READY`, `STALE`, or `ERROR`, the  `provider status` accessor must support possible value `RECONCILING`.",
-                    "RFC 2119 keyword": null,
+                    "content": "In addition to `NOT_READY`, `READY`, `STALE`, `ERROR`, or `FATAL`, the `provider status` accessor MUST support possible value `RECONCILING`.",
+                    "RFC 2119 keyword": "MUST",
                     "children": []
                 }
             ]
         },
         {
             "id": "Requirement 1.7.3",
             "machine_id": "requirement_1_7_3",
-            "content": "The client's `provider status` accessor MUST indicate `READY` if the `initialize` function of the associated provider terminates normally.",
+            "content": "The `provider status` MUST indicate `READY` if the `initialize` function of the associated provider terminates normally.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
         {
             "id": "Requirement 1.7.4",
             "machine_id": "requirement_1_7_4",
-            "content": "The client's `provider status` accessor MUST indicate `ERROR` if the `initialize` function of the associated provider terminates abnormally.",
+            "content": "The `provider status` MUST indicate `ERROR` if the `initialize` function of the associated provider terminates abnormally.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
         {
             "id": "Requirement 1.7.5",
             "machine_id": "requirement_1_7_5",
-            "content": "The client's `provider status` accessor MUST indicate `FATAL` if the `initialize` function of the associated provider terminates abnormally and indicates `error code` `PROVIDER_FATAL`.",
+            "content": "The `provider status` MUST indicate `FATAL` if the `initialize` function of the associated provider terminates abnormally and indicates `error code` `PROVIDER_FATAL`.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
@@ -361,7 +361,7 @@
         {
             "id": "Requirement 1.7.9",
             "machine_id": "requirement_1_7_9",
-            "content": "The client's `provider status` accessor MUST indicate `NOT_READY` once the `shutdown` function of the associated provider terminates.",
+            "content": "The `provider status` MUST indicate `NOT_READY` once the `shutdown` function of the associated provider terminates.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
@@ -564,6 +564,49 @@
             "RFC 2119 keyword": "MAY",
             "children": []
         },
+        {
+            "id": "Requirement 2.8.1",
+            "machine_id": "requirement_2_8_1",
+            "content": "The provider MUST define a `status` accessor which indicates the provider's current readiness, with possible values `NOT_READY`, `READY`, `STALE`, `ERROR`, or `FATAL`.",
+            "RFC 2119 keyword": "MUST",
+            "children": []
+        },
+        {
+            "id": "Condition 2.8.2",
+            "machine_id": "condition_2_8_2",
+            "content": "The implementation uses the static-context paradigm.",
+            "RFC 2119 keyword": null,
+            "children": [
+                {
+                    "id": "Conditional Requirement 2.8.2.1",
+                    "machine_id": "conditional_requirement_2_8_2_1",
+                    "content": "In addition to `NOT_READY`, `READY`, `STALE`, `ERROR`, or `FATAL`, the provider's `status` accessor MUST support possible value `RECONCILING`.",
+                    "RFC 2119 keyword": "MUST",
+                    "children": []
+                }
+            ]
+        },
+        {
+            "id": "Requirement 2.8.3",
+            "machine_id": "requirement_2_8_3",
+            "content": "The provider's `status` MUST be `NOT_READY` before `initialize` is called and after `shutdown` terminates.",
+            "RFC 2119 keyword": "MUST",
+            "children": []
+        },
+        {
+            "id": "Requirement 2.8.4",
+            "machine_id": "requirement_2_8_4",
+            "content": "The provider's `status` accessor MUST be safe for concurrent access.",
+            "RFC 2119 keyword": "MUST",
+            "children": []
+        },
+        {
+            "id": "Requirement 2.8.5",
+            "machine_id": "requirement_2_8_5",
+            "content": "Status changes and any associated event emissions MUST be atomic from the perspective of external observers.",
+            "RFC 2119 keyword": "MUST",
+            "children": []
+        },
         {
             "id": "Requirement 3.1.1",
             "machine_id": "requirement_3_1_1",
@@ -984,7 +1027,7 @@
         {
             "id": "Requirement 5.1.1",
             "machine_id": "requirement_5_1_1",
-            "content": "The `provider` MAY define a mechanism for signaling the occurrence of one of a set of events, including `PROVIDER_READY`, `PROVIDER_ERROR`, `PROVIDER_CONFIGURATION_CHANGED` and `PROVIDER_STALE`, with a `provider event details` payload.",
+            "content": "The `provider` MAY define a mechanism for signaling the occurrence of one of a set of events, including `PROVIDER_READY`, `PROVIDER_ERROR`, `PROVIDER_CONFIGURATION_CHANGED`, `PROVIDER_STALE`, `PROVIDER_RECONCILING`, and `PROVIDER_CONTEXT_CHANGED`, with a `provider event details` payload.",
             "RFC 2119 keyword": "MAY",
             "children": []
         },
@@ -1118,7 +1161,7 @@
         {
             "id": "Requirement 5.3.5",
             "machine_id": "requirement_5_3_5",
-            "content": "If the provider emits an event, the value of the client's `provider status` MUST be updated to the status associated with that event **before** the SDK invokes any event handlers for that event, so that handlers observe a consistent status.",
+            "content": "When a provider emits an event, the value of the `provider status` MUST reflect the status associated with that event **before** any event handlers for that event are invoked, so that handlers observe a consistent status.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },

specification/README.md

@@ -21,6 +21,7 @@ sidebar_position: 0
 - [Appendix B: Gherkin Suites](./appendix-b-gherkin-suites.md)
 - [Appendix C: OFREP](./appendix-c/index.md)
 - [Appendix D: Observability](./appendix-d-observability.md)
+- [Appendix E: Migrations](./appendix-e-migrations.md)
 
 ## Conformance
 

specification/appendix-e-migrations.md

@@ -0,0 +1,104 @@
+---
+id: appendix-e
+title: "Appendix E: Migrations"
+description: Migration guidance for breaking spec changes
+sidebar_position: 6
+---
+
+# Appendix E: Migrations
+
+This appendix provides non-normative guidance for provider authors and SDK authors on migrating to new or changed specification requirements.
+
+## Provider Status Ownership
+
+### Background
+
+Prior to `v0.9.0`, provider status (e.g. `NOT_READY`, `READY`, `ERROR`) was managed by the SDK on behalf of the provider.
+The SDK would set status and emit events after lifecycle methods (`initialize`, `shutdown`, `on context change`) returned.
+This created a race condition in multi-threaded SDKs: the provider could change its own state (e.g. emit an error event from a background thread) in the window between the lifecycle method returning and the SDK writing its post-lifecycle status and emitting the corresponding event.
+The result was incorrect event ordering and inconsistent status.
+
+The spec now requires providers to own their status and emit events atomically with status transitions (see [provider status](./sections/02-providers.md#28-provider-status)).
+
+### For provider authors
+
+Providers are now responsible for maintaining their own `status` and emitting events atomically with status transitions.
+
+#### What to implement
+
+- A `status` accessor returning the provider's current readiness: `NOT_READY`, `READY`, `STALE`, `ERROR`, or `FATAL` (plus `RECONCILING` in the static-context paradigm)
+- `status` must be `NOT_READY` before `initialize` is called and after `shutdown` terminates
+- `status` must be safe for concurrent access
+- Status transitions and associated event emissions must be atomic from the perspective of external observers; set the status before emitting the corresponding event
+
+#### The `StateManagingProvider` interface
+
+To signal to the SDK that your provider manages its own status, implement an opt-in interface (or equivalent mechanism) defined by the SDK.
+This interface should expose:
+
+- A `status` accessor that returns the provider's current status
+- A discriminant or marker (e.g. an additional interface, a boolean property, or a type-level tag) that allows the SDK to detect at registration time that the provider manages its own state
+
+Providers that do not implement this interface will continue to have their status managed by the SDK.
+This legacy behavior is deprecated and will be removed in the next major version.
+
+### For SDK authors
+
+SDKs must detect whether a registered provider manages its own state and branch behavior accordingly.
+
+#### Detecting state-managing providers
+
+At registration time, check whether the provider implements the `StateManagingProvider` interface (or equivalent).
+Store this as a flag on the internal provider wrapper for use during lifecycle calls and event handling.
+
+#### SDK wrapper behavior
+
+SDKs typically wrap registered providers in an internal adapter (e.g. a "provider wrapper" or "state manager") that mediates lifecycle calls and event forwarding.
+The wrapper should branch based on whether the registered provider implements the state-managing interface.
+
+```mermaid
+flowchart TD
+    A[Provider registered with SDK] --> B{Implements state-managing interface?}
+
+    B -- Yes --> C[SDK wrapper delegates status to provider]
+    C --> C1[initialize / shutdown / onContextChange: SDK skips state writes AND event emissions]
+    C --> C2[Provider events: SDK skips state writes]
+    C --> C3[status: reads from provider directly]
+
+    B -- No --> D[SDK wrapper manages state internally - legacy, deprecated]
+    D --> D1[initialize / shutdown / onContextChange: SDK sets state AND emits events after return]
+    D --> D2[Provider events: SDK updates state on emit]
+    D --> D3[status: reads from SDK wrapper]
+
+    C1 --> E[Provider-emitted events still propagate to registered handlers]
+    C2 --> E
+    C3 --> E
+    D1 --> E
+    D2 --> E
+    D3 --> E
+```
+
+#### What the SDK skips for state-managing providers
+
+For providers that implement the state-managing interface, the SDK must not perform any of the following actions that it would normally perform for legacy providers:
+
+- Setting status to `READY` after `initialize()` succeeds
+- Setting status to `ERROR` or `FATAL` after `initialize()` fails
+- Setting status to `NOT_READY` after `shutdown()` completes
+- Emitting `PROVIDER_READY` or `PROVIDER_ERROR` events after `initialize()`
+- Updating status when the provider emits events at runtime (the provider already set its own status atomically with the event)
+- (Static-context paradigm only) Setting `RECONCILING` status, emitting `PROVIDER_RECONCILING`, setting `READY`/`ERROR` status, or emitting `PROVIDER_CONTEXT_CHANGED`/`PROVIDER_ERROR` during `on context change` handling
+
+#### What the SDK still does for all providers
+
+Regardless of whether the provider manages its own state, the SDK continues to:
+
+- Call `initialize()`, `shutdown()`, and `on context change` lifecycle methods on the provider
+- Forward provider-emitted events to registered domain and API-level event handlers
+- Run late-attached handlers immediately if the provider is already in the associated state
+- Enforce short-circuit behavior for `NOT_READY` and `FATAL` statuses during flag evaluation
+
+#### Deprecation
+
+The legacy path (SDK-managed status) should be deprecated in the release that introduces the state-managing interface, with removal targeted for the next major version.
+SDK authors should update any first-party providers and provider base classes to implement the new interface.

specification/sections/01-flag-evaluation.md

@@ -421,8 +421,8 @@ This is especially useful for testing purposes to restore the API to a known sta
 
 ### 1.7. Provider Lifecycle Management
 
-The implementation maintains an internal representation of the state of configured providers, tracking the lifecycle of each provider.
-This state of the provider is exposed on associated `clients`.
+Providers own their current status (see [provider status](./02-providers.md#28-provider-status)).
+The `client`'s `provider status` accessor delegates to the associated provider's `status` accessor, and SDKs surface provider-emitted events to registered handlers.
 
 The diagram below illustrates the possible states and transitions of the `state` field for a provider during the provider lifecycle.
 
@@ -463,9 +463,9 @@ stateDiagram-v2
 
 > The `client` **MUST** define a `provider status` accessor which indicates the readiness of the associated provider, with possible values `NOT_READY`, `READY`, `STALE`, `ERROR`, or `FATAL`.
 
-The SDK at all times maintains an up-to-date state corresponding to the success/failure of the last lifecycle method (`initialize`, `shutdown`, `on context change`) or emitted event.
+The client's `provider status` accessor delegates to the associated provider's `status` accessor, which the provider keeps in sync with the success/failure of the last lifecycle method (`initialize`, `shutdown`, `on context change`) or emitted event.
 
-see [provider status](../types.md#provider-status)
+see [provider status](../types.md#provider-status), [provider status requirements](./02-providers.md#28-provider-status)
 
 #### Condition 1.7.2
 
@@ -477,27 +477,30 @@ see: [static-context paradigm](../glossary.md#static-context-paradigm)
 
 ##### Conditional Requirement 1.7.2.1
 
-> In addition to `NOT_READY`, `READY`, `STALE`, or `ERROR`, the  `provider status` accessor must support possible value `RECONCILING`.
+> In addition to `NOT_READY`, `READY`, `STALE`, `ERROR`, or `FATAL`, the `provider status` accessor **MUST** support possible value `RECONCILING`.
 
-In the static context paradigm, the implementation must define a `provider status` indicating that a provider is reconciling its internal state due to a context change.
+In the static context paradigm, the implementation **MUST** define a `provider status` indicating that a provider is reconciling its internal state due to a context change.
 
 #### Requirement 1.7.3
 
-> The client's `provider status` accessor **MUST** indicate `READY` if the `initialize` function of the associated provider terminates normally.
+> The `provider status` **MUST** indicate `READY` if the `initialize` function of the associated provider terminates normally.
 
 Once the provider has initialized, the `provider status` should indicate the provider is ready to be used to evaluate flags.
+The provider is responsible for its own status transition; the client's `provider status` accessor reflects it.
 
 #### Requirement 1.7.4
 
-> The client's `provider status` accessor **MUST** indicate `ERROR` if the `initialize` function of the associated provider terminates abnormally.
+> The `provider status` **MUST** indicate `ERROR` if the `initialize` function of the associated provider terminates abnormally.
 
 If the provider has failed to initialize, the `provider status` should indicate the provider is in an error state.
+The provider is responsible for its own status transition; the client's `provider status` accessor reflects it.
 
 #### Requirement 1.7.5
 
-> The client's `provider status` accessor **MUST** indicate `FATAL` if the `initialize` function of the associated provider terminates abnormally and indicates `error code` `PROVIDER_FATAL`.
+> The `provider status` **MUST** indicate `FATAL` if the `initialize` function of the associated provider terminates abnormally and indicates `error code` `PROVIDER_FATAL`.
 
 If the provider has failed to initialize, the `provider status` should indicate the provider is in an error state.
+The provider is responsible for its own status transition; the client's `provider status` accessor reflects it.
 
 #### Requirement 1.7.6
 
@@ -527,9 +530,10 @@ see: [error codes](../types.md#error-code)
 
 #### Requirement 1.7.9
 
-> The client's `provider status` accessor **MUST** indicate `NOT_READY` once the `shutdown` function of the associated provider terminates.
+> The `provider status` **MUST** indicate `NOT_READY` once the `shutdown` function of the associated provider terminates.
 
 Regardless of the success of the provider's `shutdown` function, the `provider status` should convey the provider is no longer ready to use once the shutdown function terminates.
+The provider is responsible for its own status transition; the client's `provider status` accessor reflects it.
 
 ### 1.8. Isolated API Instances