Fix context merge order: Transaction before Client per spec (#87)

* Fix context merge order: Transaction before Client per spec

* Add test for context merge order: client overrides transaction

* Fix context merge order in docs and ScalaDoc

Author: EtaCassiopeia

core/src/main/scala/zio/openfeature/FeatureFlags.scala

@@ -108,7 +108,7 @@ trait FeatureFlags {
 
   /** Set the client-level evaluation context.
     *
-    * Per OpenFeature spec, context merges in order: API (global) -> Client -> Transaction -> Invocation. Client context
+    * Per OpenFeature spec, context merges in order: API (global) -> Transaction -> Client -> Invocation. Client context
     * is persisted on this FeatureFlags instance.
     */
   def setClientContext(ctx: EvaluationContext): UIO[Unit]

core/src/main/scala/zio/openfeature/FeatureFlagsLive.scala

@@ -111,7 +111,7 @@ final private[openfeature] class FeatureFlagsLive(
     }
   }
 
-  // Context merges in order per OpenFeature spec: API (global) -> Client -> Transaction -> Invocation
+  // Context merges per OpenFeature spec: API (global) -> Transaction -> Client -> FiberLocal -> Invocation
   private def effectiveContext(invocation: EvaluationContext): UIO[EvaluationContext] =
     for {
       global      <- state.globalContextRef.get
@@ -120,9 +120,9 @@ final private[openfeature] class FeatureFlagsLive(
       transaction <- state.transactionRef.get
       txContext = transaction.map(_.context).getOrElse(EvaluationContext.empty)
     } yield global
+      .merge(txContext)
       .merge(clientCtx)
       .merge(fiberLocal)
-      .merge(txContext)
       .merge(invocation)
 
   private def runWithHooks[A: FlagType](

docs/architecture.md

@@ -183,12 +183,12 @@ Evaluation context flows through five levels (per OpenFeature spec), with later
 | Level | Scope | Use Case |
 |:------|:------|:---------|
 | **Global** | Application-wide | App version, environment, deployment region |
+| **Transaction** | Within transaction block | Test overrides, experiment context |
 | **Client** | FeatureFlags instance | Service name, region |
 | **Scoped** | Block of code (via `withContext`) | User session, request context |
-| **Transaction** | Within transaction block | Test overrides, experiment context |
 | **Invocation** | Single evaluation | One-off targeting attributes |
 
-Contexts merge with higher-precedence levels overriding lower ones: `Invocation > Transaction > Scoped > Client > Global`.
+Contexts merge with higher-precedence levels overriding lower ones: `Invocation > Scoped > Client > Transaction > Global`.
 
 See [Evaluation Context]({{ site.baseurl }}/context) for detailed usage, attribute types, and practical examples.
 

docs/context.md

@@ -22,9 +22,9 @@ Evaluation context provides information about the current evaluation environment
 ZIO OpenFeature supports a hierarchical context system with five levels (per OpenFeature spec):
 
 1. **Global context** - API-level, shared across all evaluations, set via `setGlobalContext`
-2. **Client context** - Client-level, persisted on the FeatureFlags instance, set via `setClientContext`
-3. **Scoped context** - Applied to a block of code via `withContext` (fiber-local)
-4. **Transaction context** - Applied within a transaction block
+2. **Transaction context** - Applied within a transaction block
+3. **Client context** - Client-level, persisted on the FeatureFlags instance, set via `setClientContext`
+4. **Scoped context** - Applied to a block of code via `withContext` (fiber-local)
 5. **Invocation context** - Passed directly to evaluation methods
 
 Contexts are merged in order, with later contexts taking precedence.
@@ -224,19 +224,19 @@ Per the OpenFeature specification, contexts are merged in this order (lowest to
 ```
 ┌──────────────────────────────────────────────────────────────┐
 │                     Final Merged Context                      │
-│  (Invocation > Transaction > Scoped > Client > Global)       │
+│  (Invocation > Scoped > Client > Transaction > Global)       │
 └──────────────────────────────────────────────────────────────┘
                             ▲
                             │
     ┌───────────────────────┼───────────────────────┐
     │                       │                       │
 ┌───┴───┐             ┌─────┴─────┐           ┌─────┴─────┐
-│Invoc. │             │Transaction│           │  Scoped   │
+│Invoc. │             │  Scoped   │           │  Client   │
 │(high) │             │  Context  │           │  Context  │
 └───────┘             └───────────┘           └───────────┘
                             │
                      ┌──────┴──────┐
-                     │   Client    │
+                     │Transaction  │
                      │  Context    │
                      └─────────────┘
                             │

docs/spec-compliance.md

@@ -102,14 +102,14 @@ FeatureFlags.booleanDetails("flag", false, context, options)
 | Client context | ✅ | `setClientContext` / `clientContext` |
 | Scoped context | ✅ | `withContext` |
 | Invocation context | ✅ | Per-evaluation parameter |
-| Context merging | ✅ | Global → Client → Scoped → Transaction → Invocation |
+| Context merging | ✅ | Global → Transaction → Client → Scoped → Invocation |
 
 ### Context Merge Order
 
 ```
 ┌──────────────────────────────────────────────────────────────┐
 │                     Final Merged Context                      │
-│  (Invocation > Transaction > Scoped > Client > Global)       │
+│  (Invocation > Scoped > Client > Transaction > Global)       │
 └──────────────────────────────────────────────────────────────┘
 ```
 

testkit/src/test/scala/zio/openfeature/testkit/FeatureFlagsSpec.scala

@@ -832,9 +832,12 @@ object FeatureFlagsSpec extends ZIOSpecDefault {
           assertTrue(effective.getString("invocation-only").contains("yes"))
         }
       }.provide(testLayer(Map("flag" -> true))),
-      test("transaction context merges between scoped and invocation") {
-        val globalCtx = EvaluationContext.empty.withAttribute("source", "global")
-        val txCtx     = EvaluationContext.empty.withAttribute("source", "transaction")
+      test(
+        "transaction context merges between global and client per spec (API -> Transaction -> Client -> Invocation)"
+      ) {
+        val globalCtx = EvaluationContext.empty.withAttribute("source", "global").withAttribute("global-only", "yes")
+        val txCtx     = EvaluationContext.empty.withAttribute("source", "transaction").withAttribute("tx-only", "yes")
+        val clientCtx = EvaluationContext.empty.withAttribute("source", "client").withAttribute("client-only", "yes")
 
         val capturedCtx = Unsafe.unsafe { implicit u =>
           Runtime.default.unsafe.run(Ref.make(Option.empty[EvaluationContext])).getOrThrow()
@@ -847,14 +850,20 @@ object FeatureFlagsSpec extends ZIOSpecDefault {
 
         for {
           _ <- FeatureFlags.setGlobalContext(globalCtx)
+          _ <- FeatureFlags.setClientContext(clientCtx)
           _ <- FeatureFlags.addHook(ctxCapture)
           _ <- FeatureFlags.transaction(context = txCtx) {
             FeatureFlags.boolean("flag", default = false)
           }
           ctx <- capturedCtx.get
         } yield {
           val effective = ctx.get
-          assertTrue(effective.getString("source").contains("transaction"))
+          // Client overrides Transaction (spec: API -> Transaction -> Client -> Invocation)
+          assertTrue(effective.getString("source").contains("client")) &&
+          // All unique attributes from each level are present
+          assertTrue(effective.getString("global-only").contains("yes")) &&
+          assertTrue(effective.getString("tx-only").contains("yes")) &&
+          assertTrue(effective.getString("client-only").contains("yes"))
         }
       }.provide(testLayer(Map("flag" -> true)))
     ),