docs: soften slot fairness claim, complete docstrings (algo #6)

app/harness/validate.py

@@ -964,8 +964,8 @@ class _QuestionSlots:
     """按题数计数的共享并发闸:峰值在飞请求恒 ≤ width(设计 v3 §2.4)。
 
     多槽获取(AR pair 一单元两题)经内部锁串行化,防多任务半持有交错死锁。
-    asyncio.Semaphore 等待队列 FIFO,任务按创建序(题型 round-robin)获得槽,
+    本类只承诺"并发上限 + 多槽获取原子性";公平性由调用方按题型 round-robin
-    即公平调度的实现载体(Codex I2)。
+    顺序创建任务实现(实践中 asyncio 等待队列近似先来先服务,但那不是本类契约)。
     """
 
     def __init__(self, width: int) -> None:
@@ -973,6 +973,13 @@ class _QuestionSlots:
 
         参数:
             width: 并发宽度(全 gate 同时在飞的题数上限),必须为正。
+
+        返回:
+            无。
+
+        关键实现细节:
+            _width 供 acquire 做超宽 fail-fast;BoundedSemaphore 使多还立即
+            ValueError 而非静默扩容;_acquire_lock 串行化多槽获取防交错死锁。
         """
         assert width > 0, f"并发宽度必须为正: {width}"
         self._width = width
@@ -1018,6 +1025,10 @@ class _QuestionSlots:
 
         返回:
             无。
+
+        关键实现细节:
+            底层为 BoundedSemaphore——多还(release 数超过 acquire)立即
+            ValueError 暴露调用方配对错误,属防御性设计。
         """
         for _ in range(n):
             self._sem.release()