fixup: reset state, run on all providers

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

specification.json

@@ -283,15 +283,15 @@
         {
             "id": "Requirement 1.6.1",
             "machine_id": "requirement_1_6_1",
-            "content": "The API MUST define a function 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 NOT call shutdown on providers which are in state `NOT_READY`.",
-            "RFC 2119 keyword": "MUST NOT",
+            "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": []
         },
         {
@@ -511,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

@@ -401,21 +401,20 @@ See [hooks](./04-hooks.md) for details.
 
 #### Requirement 1.6.1
 
-> The API **MUST** define a function 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 active 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 NOT** call shutdown on providers which are in state `NOT_READY`.
+> The API's `shutdown` function **MUST** reset all state of the API, removing all hooks, event handlers, and providers.
 
-With respect to the lifecycle of a given active provider, the global API object's `shutdown` function should be idempotent; multiple calls to `shutdown` should result in only a single execution of the provider's `shutdown` function.
-Implementations should take care to await or cancel the initialization of providers if `shutdown` is called while providers are still being initialized, and have yet to transition to `READY` or some other state.
-
-see: [`shutdown`](./02-providers.md#25-shutdown)
+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
 

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)