fix: clarify hook ordering (#315)

This clarifies some ambiguity in hook execution order, mentioned in
#164:

> The issue here is that the overall hook execution order would vary if
any of these hooks have more than one entry. For example:
> 
> ```
> API = [A, B]
> Client = [C, D]
> Invocation = [E, F]
> Provider = [G, H]
> 
> # `before` list
> before_hooks = API + Client + Invocation + Provider
> 
> # spreading directly (like Python)
> list1 = Provider + Invocation + Client + API
> # results in [G, H, E, F, C, D, A, B]
> 
> # reversing the before list (like JavaScript)
> list2 = before_hooks[:]
> list2.reverse()
> # results in [H, G, F, E, D, C, B, A]
> ```

This change makes clear that `[H, G, F, E, D, C, B, A]` is the correct
answer here, which is the more intuitive choice, in my opinion.

This is also one of the few (only?) normative spec points that isn't a
single sentence, but instead has point-form clauses, so I've also
attempted to fix that.

I've work-shopped this with a few people and they interpreted it
correctly, though admittedly, the term "stack-wise" is doing a lot of
work here. I'm hopeful that our audience is familiar enough with that
sort of term that the intent is clear.

I believe there's a few SDKs where this is incorrectly implemented, I'll
audit those and create issues if this is merged. I don't expect that
such an implementation change will significantly impact anyone.

---------

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

Author: toddbaert

specification.json

@@ -865,7 +865,7 @@
         {
             "id": "Requirement 4.4.2",
             "machine_id": "requirement_4_4_2",
-            "content": "Hooks MUST be evaluated in the following order:  - before: API, Client, Invocation, Provider - after: Provider, Invocation, Client, API - error (if applicable): Provider, Invocation, Client, API - finally: Provider, Invocation, Client, API",
+            "content": "Hooks MUST be executed \"stack-wise\" with respect to flag resolution, prioritizing increasing specificity (API, Client, Invocation, Provider) first, and the order in which they were added second.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },

specification/sections/04-hooks.md

@@ -246,12 +246,24 @@ client.getValue('my-flag', 'defaultValue', new Hook3());
 
 #### Requirement 4.4.2
 
-> Hooks **MUST** be evaluated in the following order:
->
-> - before: API, Client, Invocation, Provider
-> - after: Provider, Invocation, Client, API
-> - error (if applicable): Provider, Invocation, Client, API
-> - finally: Provider, Invocation, Client, API
+> Hooks **MUST** be executed "stack-wise" with respect to flag resolution, prioritizing increasing specificity (API, Client, Invocation, Provider) first, and the order in which they were added second.
+
+Before flag resolution (the `before` stage), hooks run in the order `API` -> `Client` -> `Invocation` -> `Provider`, and within those, in the order in which they were added. 
+After flag evaluation (the `after`, `error`, or `finally` stages), hooks run in the order `Provider` -> `Invocation` -> `Client` -> `API`, and within those, in reverse of the order in which they were added.
+This achieves intuitive "stack-like" or "LIFO" behavior for side effects and transformations.
+
+```
+Given hooks A - H, each implementing the both the `before` and `after` stages, added at the following levels and order:
+
+API: [A, B]
+Client: [C, D]
+Invocation: [E, F]
+Provider: [G, H]
+
+The expected order of execution is:
+
+A.before -> B.before -> C.before -> D.before -> E.before -> F.before -> G.before -> H.before -> flagResolution -> H.after -> G.after -> F.after -> E.after -> D.after -> C.after -> B.after -> A.after
+```
 
 #### Requirement 4.4.3