feat: add point 1.6.2, 2.5.3 about shutdown details

specification.json

@@ -283,7 +283,14 @@
         {
             "id": "Requirement 1.6.1",
             "machine_id": "requirement_1_6_1",
-            "content": "The API MUST define a mechanism to propagate a shutdown request to active providers.",
+            "content": "The API MUST define a function to propagate a shutdown request to all providers.",
+            "RFC 2119 keyword": "MUST",
+            "children": []
+        },
+        {
+            "id": "Requirement 1.6.2",
+            "machine_id": "requirement_1_6_2",
+            "content": "The API's `shutdown` function MUST reset all state of the API, removing all hooks, event handlers, and providers.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
@@ -504,7 +511,14 @@
         {
             "id": "Requirement 2.5.2",
             "machine_id": "requirement_2_5_2",
-            "content": "After a provider's shutdown function has terminated, the provider SHOULD revert to its uninitialized state.",
+            "content": "After a provider's `shutdown` function has terminated, the provider SHOULD revert to its uninitialized state.",
+            "RFC 2119 keyword": "SHOULD",
+            "children": []
+        },
+        {
+            "id": "Requirement 2.5.3",
+            "machine_id": "requirement_2_5_3",
+            "content": "A Provider's `shutdown` function SHOULD be idempotent.",
             "RFC 2119 keyword": "SHOULD",
             "children": []
         },

specification/sections/01-flag-evaluation.md

@@ -399,15 +399,27 @@ See [hooks](./04-hooks.md) for details.
 
 [![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
 
+The API's `shutdown` function defines a means of graceful shutdown, calling the `shutdown` function on all providers, allowing them to flush telemetry, clean up connections, and release any relevant resources.
+It also provides a means of resetting the API object to its default state, removing all hooks, event handlers, providers, and setting a "No-op provider"; this is useful for testing purposes.
+It's recommended that application-authors to call this function on application shutdown, and after the completion of test suites which make use of the SDK.
+
 #### Requirement 1.6.1
 
-> The API **MUST** define a mechanism to propagate a shutdown request to active providers.
+> The API **MUST** define a function to propagate a shutdown request to all providers.
 
-The global API object might expose a `shutdown` function, which will call the respective `shutdown` function on the registered providers.
+The global API object defines a `shutdown` function, which will call the respective `shutdown` function on the active providers.
 Alternatively, implementations might leverage language idioms such as auto-disposable interfaces or some means of cancellation signal propagation to allow for graceful shutdown.
+This shutdown function unconditionally calls the shutdown function on all registered providers, regardless of their state. 
 
 see: [`shutdown`](./02-providers.md#25-shutdown)
 
+#### Requirement 1.6.2
+
+> The API's `shutdown` function **MUST** reset all state of the API, removing all hooks, event handlers, and providers.
+
+After shutting down all providers, the `shutdown` function resets the state of the API.
+This is especially useful for testing purposes to restore the API to a known state.
+
 ### 1.7. Provider Lifecycle Management
 
 The implementation maintains an internal representation of the state of configured providers, tracking the lifecycle of each provider.

specification/sections/02-providers.md

@@ -225,11 +225,20 @@ class MyProvider implements Provider, AutoDisposable {
 
 #### Requirement 2.5.2
 
-> After a provider's shutdown function has terminated, the provider **SHOULD** revert to its uninitialized state.
+> After a provider's `shutdown` function has terminated, the provider **SHOULD** revert to its uninitialized state.
 
 If a provider requires initialization, once it's shut down, it must transition to its uninitialized state.
 Some providers may allow reinitialization from this state.
 Providers not requiring initialization are assumed to be ready at all times.
+Providers in the process of initializing abort initialization if shutdown is called while they are still starting up.
+
+see: [initialization](#24-initialization)
+
+#### Requirement 2.5.3
+
+> A Provider's `shutdown` function **SHOULD** be idempotent.
+
+If a provider's `shutdown` function has been called, subsequent calls (without an intervening call to `initialize`) should have no effect.
 
 see: [initialization](#24-initialization)