Merge branch 'main' into feat/context-propagation

specification.json

@@ -31,7 +31,7 @@
         {
             "id": "Requirement 1.1.2.4",
             "machine_id": "requirement_1_1_2_4",
-            "content": "The `API` SHOULD provide functions to set a provider and wait for the `initialize` function to return or throw.",
+            "content": "The `API` SHOULD provide functions to set a provider and wait for the `initialize` function to complete or abnormally terminate.",
             "RFC 2119 keyword": "SHOULD",
             "children": []
         },

specification/sections/01-flag-evaluation.md

@@ -57,7 +57,7 @@ see [shutdown](./02-providers.md#25-shutdown), [setting a provider](#setting-a-p
 
 #### Requirement 1.1.2.4
 
-> The `API` **SHOULD** provide functions to set a provider and wait for the `initialize` function to return or throw.
+> The `API` **SHOULD** provide functions to set a provider and wait for the `initialize` function to complete or abnormally terminate.
 
 This function not only sets the provider, but ensures that the provider is ready (or in error) before returning or settling.
 
@@ -74,6 +74,7 @@ Client client = OpenFeatureAPI.getInstance().getClient('domain-1');
 ```
 
 Though it's possible to use [events](./05-events.md) to await provider readiness, such functions can make things simpler for `application authors` and `integrators`.
+Implementations indicate an error in a manner idiomatic to the language in use (returning an error, throwing an exception, etc).
 
 #### Requirement 1.1.3
 

specification/types.md

@@ -72,6 +72,28 @@ A set of pre-defined reasons is enumerated below:
 | STALE           | The resolved value is non-authoritative or possibly out of date                                                                  |
 | ERROR           | The resolved value was the result of an error.                                                                                   |
 
+> [!NOTE]
+> The `reason` should not be limited to the reasons enumerated above. It can be any of the pre-defined reasons, or
+> any string value. Some type systems have features which can increase the ergonomics of `reason`, for instance a union
+> of pre-defined types with a string, or a rust-style enumeration which allows for enumerated values to have associated
+> content.
+
+```rust
+enum Reason {
+    Static,
+    Default,
+    TargetingMatch,
+    Split,
+    Cached,
+    Unknown,
+    Stale,
+    Error,
+    Other(String)
+}
+
+let myReason = Reason::Other("my-reason".to_string());
+```
+
 > [!NOTE]
 > The `resolution details` structure is not exposed to the Application Author.
 > It defines the data which Provider Authors must return when resolving the value of flags.