docs(async/unstable): document known race condition in circuit breaker

Author: tomas-zijdemans

async/unstable_circuit_breaker.ts

@@ -431,6 +431,30 @@ export class CircuitBreaker<T = unknown> {
    * @returns The result of the operation.
    * @throws {CircuitBreakerOpenError} If circuit is open.
    */
+  /*
+   * NOTE: Known race condition in half-open state concurrent tracking.
+   *
+   * The `halfOpenInFlight` counter uses a read-modify-write pattern that is
+   * not atomic. Under high concurrency, more requests than `halfOpenMaxConcurrent`
+   * may slip through.
+   *
+   * Future fix: Once `@std/async/unstable-semaphore` stabilizes, use it to
+   * guard state transitions:
+   *
+   * ```ts
+   * import { Semaphore } from "@std/async/semaphore";
+   *
+   * #stateMutex = new Semaphore(1);
+   *
+   * async execute<R extends T>(fn: () => Promise<R>): Promise<R> {
+   *   {
+   *     using _lock = await this.#stateMutex.acquire();
+   *     // Check state and acquire half-open slot atomically
+   *   }
+   *   // Execute fn() outside the lock
+   * }
+   * ```
+   */
   async execute<R extends T>(fn: () => Promise<R>): Promise<R> {
     const currentTime = Date.now();
     const currentState = this.#resolveCurrentState();