fix: additional clarity, events fixes

* Adds additional clarity regarding provider/client name mapping, as well as intent.
* Requires that READY events only run immediately for clients when the provider is already ready.
* Replaces client-name for provider-name in events-details.

specification.json

@@ -31,7 +31,7 @@
         {
             "id": "Requirement 1.1.3",
             "machine_id": "requirement_1_1_3",
-            "content": "The `API` MUST provide a function to bind a given `provider` to one or more client `name`s. If the client-name already has a bound provider, it is overwritten with the new mapping.",
+            "content": "The `API` MUST provide a function to bind a given `provider` to a client `name`. If the client-name already has a bound provider, it is overwritten with the new mapping.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
@@ -675,7 +675,7 @@
         {
             "id": "Requirement 5.2.3",
             "machine_id": "requirement_5_2_3",
-            "content": "The `event details` MUST contain the `client name` associated with the event.",
+            "content": "The `event details` MUST contain the `provider name` associated with the event.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
@@ -724,7 +724,7 @@
         {
             "id": "Requirement 5.3.3",
             "machine_id": "requirement_5_3_3",
-            "content": "`PROVIDER_READY` handlers attached after the provider is already in a ready state MUST run immediately.",
+            "content": "Client `PROVIDER_READY` handlers attached after the provider is in a ready state MUST run immediately.",
             "RFC 2119 keyword": "MUST",
             "children": []
         }

specification/sections/01-flag-evaluation.md

@@ -31,9 +31,9 @@ It's important that multiple instances of the `API` not be active, so that state
 OpenFeature.setProvider(new MyProvider());
 ```
 
-This provider is used if there is not a more specific client name binding. (see later requirements).
+This provider is used if a client is not bound to a specific provider through its name.
 
-See [provider](./02-providers.md) for details.
+See [provider](./02-providers.md), [creating clients](#creating-clients).
 
 #### Requirement 1.1.2.2
 
@@ -56,12 +56,16 @@ see: [shutdown](./02-providers.md#25-shutdown), [setting a provider](#setting-a-
 
 #### Requirement 1.1.3
 
-> The `API` **MUST** provide a function to bind a given `provider` to one or more client `name`s. If the client-name already has a bound provider, it is overwritten with the new mapping.
+> The `API` **MUST** provide a function to bind a given `provider` to a client `name`. If the client-name already has a bound provider, it is overwritten with the new mapping.
 
 ```java
 OpenFeature.setProvider("client-name", new MyProvider());
 ```
 
+Named clients can be associated with a particular provider by supplying a matching name when the provider is set.
+
+See [creating clients](#creating-clients).
+
 #### Requirement 1.1.4
 
 > The `API` **MUST** provide a function to add `hooks` which accepts one or more API-conformant `hooks`, and appends them to the collection of any previously added hooks. When new hooks are added, previously added hooks are not removed.
@@ -84,20 +88,23 @@ OpenFeature.getProviderMetadata();
 
 See [provider](./02-providers.md) for details.
 
+### Creating clients
+
 #### Requirement 1.1.6
 
 > The `API` **MUST** provide a function for creating a `client` which accepts the following options:
 >
 > - name (optional): A logical string identifier for the client.
 
-```typescript
+```java
 // example client creation and retrieval
-OpenFeature.getClient({
-  name: "my-openfeature-client",
-});
+OpenFeature.getClient(name: "my-named-client");
 ```
 
-The name is a logical identifier for the client.
+The name is a logical identifier for the client which may be associated with a particular provider.
+If a client name is not bound to a particular provider, the client is associated with the default provider.
+
+See [setting a provider](#setting-a-provider) for details.
 
 #### Requirement 1.1.7
 

specification/sections/05-events.md

@@ -1,5 +1,5 @@
 ---
-title: Events Extensions
+title: Events
 description: Specification defining event semantics
 toc_max_heading_level: 4
 ---
@@ -80,10 +80,12 @@ see: [provider events](#51-provider-events), [`provider event types`](../types.m
 
 #### Requirement 5.2.3
 
-> The `event details` **MUST** contain the `client name` associated with the event.
+> The `event details` **MUST** contain the `provider name` associated with the event.
 
-The `client name` indicates the client/provider pair with which the event is associated.
-This is especially relevant for event handlers which are attached to the `API`, not a particular client.
+The `provider name` indicates the provider from which the event originated.
+This is especially relevant for global event handlers used for general monitoring, such as alerting on provider errors. 
+
+See [setting a provider](./01-flag-evaluation.md#setting-a-provider), [creating clients](./01-flag-evaluation.md#creating-clients). 
 
 #### Requirement 5.2.4
 
@@ -99,7 +101,7 @@ see: [`event details`](../types.md#event-details)
 
 > Event handlers **MUST** persist across `provider` changes.
 
-If a provider is changed, existing event handlers will still fire.
+If the underlying provider is changed, existing client and API event handlers will still fire.
 This means that the order of provider configuration and event handler addition is independent.
 
 #### Requirement 5.2.7
@@ -134,6 +136,10 @@ See [provider initialization](./02-providers.md#24-initialization) and [setting
 
 #### Requirement 5.3.3
 
-> `PROVIDER_READY` handlers attached after the provider is already in a ready state **MUST** run immediately.
+> Client `PROVIDER_READY` handlers attached after the provider is in a ready state **MUST** run immediately.
 
-See [provider initialization](./02-providers.md#24-initialization) and [setting a provider](./01-flag-evaluation.md#setting-a-provider).
+_Application authors_ may attach readiness handlers to be confident that system is ready to evaluate flags.
+If such handlers are attached after the provider underlying the client has already been initialized, they should run immediately.
+API (global) handlers have no such requirement, as they are potentially bound to multiple providers and are used primarily for diagnostic purposes.
+
+See [provider initialization](./02-providers.md#24-initialization), [setting a provider](./01-flag-evaluation.md#setting-a-provider).