Clarify comments on versioning and race conditions

Improved documentation in EvaluationStorage and its tests to clarify the behavior of the version counter and update flag, especially regarding race conditions and expected outcomes during concurrent operations.

Author: duyhungtnn

Bucketeer/Sources/Internal/Evaluation/EvaluationStorage.swift

@@ -51,11 +51,10 @@ protocol EvaluationStorage {
 /// whole across app restarts.
 ///
 /// The ephemeral nature of the version counter is intentional. We employ an Optimistic Locking pattern where the integer value does not need to persist across app restarts:
-/// On Restart: The persisted isUpdated flag is authoritative. If true, we trigger an immediate sync, regardless of the version.
-/// During Runtime: The version acts as a transaction ID to safely handle race conditions where user attributes change while a background fetch is in progress.
-/// Correctness: The update flag is only cleared via a Compare-and-Swap check (currentVersion == capturedVersion).
-/// If the user modifies attributes during a fetch, the version increments, the check fails, and the flag remains true to schedule a subsequent sync.
-
+/// - On restart: The persisted `isUpdated` flag is authoritative. If `true`, an immediate sync is triggered, regardless of the version.
+/// - During runtime: The `version` acts as a transaction ID to safely handle race conditions where user attributes change while a background fetch is in progress.
+/// - Correctness: The update flag is only cleared via a compare-and-swap check (`currentVersion == capturedVersion`).
+/// If the user modifies attributes during a fetch, the `version` increments, the check fails, and the flag remains `true` to schedule a subsequent sync.
 struct UserAttributesState {
     let version: Int
     let isUpdated: Bool

BucketeerTests/EvaluationStorageTests.swift

@@ -324,8 +324,10 @@ final class EvaluationStorageTests: XCTestCase {
         // Wait for all operations to complete
         let result = group.wait(timeout: .now() + 10.0)
         XCTAssertEqual(result, .success, "Test timed out")
-        // In 99.9% of runs, storage.userAttributesUpdated resolves to false, but we cannot guarantee this behavior every time due to async nature.
-        // The critical check is that the version counter matches the number of updates, proving no race conditions when incrementing.
+        // Due to the inherent race between concurrent "update" and "clear" operations, the final value of
+        // `userAttributesUpdated` can legitimately be either true or false. This test therefore only asserts
+        // that the version counter matches the number of update calls, proving there are no race conditions
+        // when incrementing the version.
         let userAttributesState = storage.userAttributesState
         XCTAssertEqual(userAttributesState.version, iterations, "Version should exactly match the number of update calls, proving no race conditions")
     }