docs: Add docs about the ProviderOperationsQueue

Signed-off-by: Fabrizio Demaria <fabrizio.f.demaria@gmail.com>

Author: fabriziodemaria

docs/AsyncProviderOperationsQueue.md

@@ -0,0 +1,288 @@
+# AsyncProviderOperationsQueue
+
+## Overview
+
+`AsyncProviderOperationsQueue` is a specialized serial async task queue that provides **operation-type-aware last-wins semantics** for handling OpenFeature provider operations. It ensures thread-safe, ordered execution of async operations while optimizing performance by coalescing redundant operations.
+
+## Key Characteristics
+
+- **Serial Execution**: Operations execute one at a time, preserving order
+- **Actor-based**: Thread-safe through Swift's actor isolation
+- **Smart Coalescing**: Automatically skips redundant operations based on last-wins semantics
+- **Continuation Management**: All callers receive completion notification, even if their operation was skipped
+
+## Core Concepts
+
+### Operation Types
+
+The queue distinguishes between two types of operations:
+
+1. **Non-Last-Wins (`lastWins: false`)**
+   - Always executes
+   - Processes in strict FIFO order
+   - Used for critical state changes that must not be skipped
+   - Examples: `setProvider()`, `clearProvider()`
+
+2. **Last-Wins (`lastWins: true`)**
+   - May be skipped if superseded by newer last-wins operations
+   - Optimizes away intermediate states
+   - Used for operations where only the final state matters
+   - Examples: `setEvaluationContext()`
+
+### Batching Logic
+
+When processing the queue, operations are grouped into "batches":
+
+- **Batch 1**: A single non-last-wins operation
+- **Batch 2**: Consecutive last-wins operations → only the last one executes
+
+## How It Works
+
+### Architecture
+
+```
+┌─────────────────────────────────────────┐
+│   AsyncProviderOperationsQueue (Actor)  │
+├─────────────────────────────────────────┤
+│  - queue: [QueuedOperation]             │
+│  - currentTask: Task<Void, Never>?      │
+├─────────────────────────────────────────┤
+│  + run(lastWins:operation:) async       │
+│  - processNext()                        │
+└─────────────────────────────────────────┘
+
+QueuedOperation {
+    operation: () async -> Void
+    continuation: CheckedContinuation<Void, Never>
+    lastWins: Bool
+}
+```
+
+### Execution Flow
+
+```
+1. Caller invokes run(lastWins:operation:)
+   ↓
+2. Operation wrapped with continuation and enqueued
+   ↓
+3. If no task running → processNext()
+   ↓
+4. Determine batch type
+   ├─ Non-last-wins: Execute single operation
+   └─ Last-wins: Find consecutive last-wins ops
+                 → Execute only the LAST one
+                 → Skip all others
+   ↓
+5. Resume ALL continuations (skipped + executed)
+   ↓
+6. Recursively processNext() until queue empty
+```
+
+### Example Scenarios
+
+#### Scenario 1: Non-Last-Wins Operations
+
+```swift
+// Queue: Empty, currentTask: nil
+
+await queue.run(lastWins: false) { setProvider(A) }     // Op1
+await queue.run(lastWins: false) { setProvider(B) }     // Op2
+await queue.run(lastWins: false) { clearProvider() }    // Op3
+
+// Execution order:
+// 1. setProvider(A)  ✓ Executed
+// 2. setProvider(B)  ✓ Executed
+// 3. clearProvider() ✓ Executed
+// All three operations execute in order
+```
+
+#### Scenario 2: Last-Wins Coalescing
+
+```swift
+// Queue: Empty, currentTask: nil
+
+await queue.run(lastWins: true) { setContext(ctx1) }   // Op1
+await queue.run(lastWins: true) { setContext(ctx2) }   // Op2
+await queue.run(lastWins: true) { setContext(ctx3) }   // Op3
+
+// Assume Op1 starts executing before Op2/Op3 are enqueued:
+// 1. setContext(ctx1) ✓ Executed (already running)
+// 2. setContext(ctx2) ✗ Skipped (superseded by ctx3)
+// 3. setContext(ctx3) ✓ Executed (last in batch)
+
+// Result: Only ctx1 and ctx3 execute
+// Op2's continuation still resumes immediately when Op3 completes
+```
+
+#### Scenario 3: Mixed Operations
+
+```swift
+// Queue: Empty, currentTask: nil
+
+await queue.run(lastWins: false) { setProvider(A) }      // Op1
+await queue.run(lastWins: true)  { setContext(ctx1) }    // Op2
+await queue.run(lastWins: true)  { setContext(ctx2) }    // Op3
+await queue.run(lastWins: false) { setProvider(B) }      // Op4
+await queue.run(lastWins: true)  { setContext(ctx3) }    // Op5
+
+// Execution flow:
+// Batch 1: [Op1] non-last-wins
+//   → setProvider(A) ✓ Executed
+
+// Batch 2: [Op2, Op3] consecutive last-wins
+//   → setContext(ctx1) ✗ Skipped
+//   → setContext(ctx2) ✓ Executed (last in batch)
+
+// Batch 3: [Op4] non-last-wins
+//   → setProvider(B) ✓ Executed
+
+// Batch 4: [Op5] last-wins
+//   → setContext(ctx3) ✓ Executed
+
+// Total executions: Op1, Op2(skipped), Op3, Op4, Op5
+```
+
+## Implementation Details
+
+### Actor Isolation
+
+The queue is implemented as a Swift `actor`, providing:
+- Automatic serialization of all property access
+- Thread-safe state management
+- No manual locking required
+
+### Continuation Management
+
+```swift
+await withCheckedContinuation { continuation in
+    queue.append(QueuedOperation(
+        operation: operation,
+        continuation: continuation,
+        lastWins: lastWins
+    ))
+    // ...
+}
+```
+
+**Key Points:**
+- Each caller gets a continuation that suspends their async context
+- Continuations resume when the operation completes OR is skipped
+- This ensures all callers receive notification, preventing deadlocks
+
+### Batch Processing Algorithm
+
+```swift
+private func processNext() {
+    guard !queue.isEmpty else { return }
+
+    let firstOp = queue[0]
+
+    if !firstOp.lastWins {
+        // Execute single non-last-wins operation
+        let op = queue.removeFirst()
+        currentTask = Task {
+            await op.operation()
+            op.continuation.resume()  // Resume caller
+            await self?.processNext()  // Process next batch
+        }
+    } else {
+        // Find consecutive last-wins operations
+        var lastWinsCount = 0
+        for op in queue {
+            if op.lastWins { lastWinsCount += 1 }
+            else { break }
+        }
+
+        // Execute only the LAST one
+        let toSkip = queue.prefix(lastWinsCount - 1)
+        let toExecute = queue[lastWinsCount - 1]
+        queue.removeFirst(lastWinsCount)
+
+        currentTask = Task {
+            await toExecute.operation()  // Execute only last
+
+            // Resume ALL continuations
+            for op in toSkip {
+                op.continuation.resume()  // Resume skipped callers
+            }
+            toExecute.continuation.resume()  // Resume executed caller
+
+            await self?.processNext()
+        }
+    }
+}
+```
+
+## Usage in OpenFeatureAPI
+
+### Non-Last-Wins Operations
+
+Used for operations that must always execute:
+
+```swift
+// Setting a provider (critical state change)
+private func setProviderInternal(provider: FeatureProvider, ...) async {
+    await unifiedQueue.run(lastWins: false) {
+        // Update state and initialize provider
+        // This MUST execute - cannot be skipped
+    }
+}
+
+// Clearing a provider (critical state change)
+private func clearProviderInternal() async {
+    await unifiedQueue.run(lastWins: false) {
+        // Clear provider state
+        // This MUST execute - cannot be skipped
+    }
+}
+```
+
+### Last-Wins Operations
+
+Used for operations where only the final state matters:
+
+```swift
+// Updating evaluation context
+private func updateContext(evaluationContext: EvaluationContext) async {
+    await unifiedQueue.run(lastWins: true) {
+        // Update context and call provider's onContextSet
+        // If multiple context updates are queued, only the last one matters
+        // Intermediate contexts can be safely skipped
+    }
+}
+```
+
+**Why Last-Wins for Context Updates?**
+
+When a user rapidly changes the evaluation context (e.g., user switches profiles multiple times), we only care about the final context. Executing intermediate `onContextSet` calls is wasteful:
+
+```swift
+// User rapidly switches profiles
+setEvaluationContext(userProfile1)  // Queued
+setEvaluationContext(userProfile2)  // Queued
+setEvaluationContext(userProfile3)  // Queued
+
+// Without coalescing: 3 expensive provider.onContextSet() calls
+// With coalescing: 1 call with userProfile3 (optimal!)
+```
+
+## Future Enhancements
+
+Potential improvements:
+
+1. **Priority Queuing**: Allow high-priority operations to jump ahead
+2. **Operation Cancellation**: Cancel pending operations explicitly
+3. **Metrics/Telemetry**: Track coalesced operations for monitoring
+4. **Configurable Coalescing**: Allow per-operation coalescing strategy
+
+## Related Files
+
+- `Sources/OpenFeature/OpenFeatureAPI.swift` - Primary consumer
+- `Tests/OpenFeatureTests/ProviderOperationsQueueTests.swift` - Comprehensive tests
+- `Sources/OpenFeature/Provider/FeatureProvider.swift` - Provider interface
+
+## References
+
+- [Swift Actors](https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html#ID645)
+- [Checked Continuations](https://developer.apple.com/documentation/swift/checkedcontinuation)
+- [OpenFeature Specification](https://openfeature.dev/specification/)