docs: record provider coordination delivery

docs/configuration/reference.md

@@ -249,8 +249,13 @@ upstreams:
     proxyAuth: {type: response}
     pool: {maxSize: 1000, shrinkDelay: 30s}
     capacity: {maxConcurrencyPerProxy: 10}
+    refill:
+      reconcileInterval: 1s
+      minimumAvailableSlots: 2000
+      targetAvailableSlots: 5000
     lifecycle: {ttl: 2m, allocationSafetyMargin: 15s}
     fetch:
+      estimatedIPsPerCall: 100
       requestInterval: 1s
       timeout: 3s
       maxAttempts: 3
@@ -315,6 +320,8 @@ proxyAuth:
 
 ### 7.3 Fetch 限制
 
+- `estimatedIPsPerCall`：冷启动时每次 Provider 调用预计返回的合法 Proxy 数，
+  同时用于 `pool.maxSize` 的 pending 预占；不得从任意 Query 或 Body 字段推断。
 - `requestInterval`：同一 Provider 请求间隔。
 - `timeout`：单次调用超时。
 - `maxAttempts`：单次补池动作最大尝试次数。
@@ -326,7 +333,18 @@ proxyAuth:
 大量缺池信号必须合并成 singleflight 或容量为 1 的通知，不能按 Gateway 请求
 数量线性触发 Provider API。
 
-### 7.4 生命周期与健康
+### 7.4 Refill 水位
+
+- `reconcileInterval`：无事件时重新读取库存的兜底周期，启动时仍立即检查一次。
+- `minimumAvailableSlots`：可用并发槽位低于该值时进入补池。
+- `targetAvailableSlots`：进入补池后持续补到该目标，再退出补池状态。
+
+三个字段均为必填正值，且 `targetAvailableSlots > minimumAvailableSlots`。
+目标不得超过 `pool.maxSize * capacity.maxConcurrencyPerProxy` 的理论上限。
+`requestInterval` 只限制外部 API 调用，不能兼任库存复核周期。pending Proxy
+按 `estimatedIPsPerCall * maxConcurrencyPerProxy` 折算槽位，避免并发补池超量。
+
+### 7.5 生命周期与健康
 
 - 明确绝对过期时间优先于响应 TTL，响应 TTL 优先于配置 `lifecycle.ttl`。
 - 距离过期不足 `allocationSafetyMargin` 时停止新分配。
@@ -372,8 +390,9 @@ Metrics 启用时 `listen` 必须是合法 `host:port`。该入口固定提供 `
 3. 非回环监听器满足认证或来源 CIDR 保护。
 4. Routing 名称唯一，正则可编译，引用的 Upstream 存在。
 5. Sequential 至少引用两个 Upstream、阈值大于零，`onUnavailable.action` 明确。
-6. 启用的 Upstream 有正数 `pool.maxSize`、并发和 Fetch 限制。
+6. 启用的 Upstream 有正数 `pool.maxSize`、并发、Refill 水位和 Fetch 估值/限制。
 7. `allocationSafetyMargin < ttl`。
 8. `fetch.maxTotal == 0` 或 `fetch.maxTotal >= pool.maxSize`。
-9. Distribution 的 fulfillment 合法，单次数量大于零。
-10. Secret 未写入日志可见配置转储。
+9. `minimumAvailableSlots < targetAvailableSlots`，且目标不超过理论并发容量。
+10. Distribution 的 fulfillment 合法，单次数量大于零。
+11. Secret 未写入日志可见配置转储。

docs/design/architecture.md

@@ -226,7 +226,7 @@ flowchart TD
     SF -->|yes| W[Coalesce signal]
     SF -->|no| R[Read current demand]
     R --> L[Acquire Provider leader]
-    L --> C{Under maxSize/maxTotal?}
+    L --> C{Below refill target and under maxSize/maxTotal?}
     C -->|no| X[Stop]
     C -->|yes| I[Wait requestInterval]
     I --> M[Acquire maxInFlight]
@@ -238,6 +238,12 @@ flowchart TD
     DD --> HC[Create FETCHED and schedule check]
 ```
 
+每个 Upstream 的 Leader、最小请求间隔和在途 Permit 由同一个 Redis 原子协调
+模块维护。Leader 租约使用 generation + 单调 epoch fence；Redis 状态整体丢失后
+生成新 generation 并重新竞选。任何续租不确定、记录损坏或 Redis 断连均
+fail-closed，不回退为本地 Leader。补池使用 minimum/target 双水位迟滞，库存
+复核期间若仍有 pending Fetch，则等待下一轮再同步 Managed，避免重复计数。
+
 ### 8.1 Empty、Duplicate 与 Error
 
 - **Empty**：HTTP/认证成功、模板执行成功，解析后合法 Proxy 数为 0。

docs/development/implementation-plan.md

@@ -213,6 +213,15 @@ Adapter 已通过真实 Redis 8.2 运行同一套公用契约；原子 Lua 覆
 计数，读取不扫描 Proxy 明细；过期清理积压或负计数时 fail-closed。Redis
 Sentinel/故障转移验证与代表性多节点压测仍待实施。
 
+Provider 分布式协调已新增公用 `Coordinator.RunLeader` / `LeaderSession` seam 与
+独立 `redisprovider` Adapter。真实 Redis 8.2 已验证同 Upstream 双实例互斥、
+generation + epoch fence、全局 requestInterval、全局 maxInFlight Permit、TTL
+回收及 Redis 状态丢失后的新 generation 自动重建；Redis 异常期间不发放请求。
+补池配置新增必填 `refill` 双水位和 `fetch.estimatedIPsPerCall`，Pool Reconciler
+已实现迟滞与 pending 槽位折算，FetchBudget 仅在无 pending 时同步 Redis 权威
+Managed。Provider Fleet、Worker Active/Reserved 汇总和 bootstrap 接线仍待完成，
+因此本轮不勾选 Task 10 的组合验收项。
+
 ## Task 11: Checker and Health Reducer
 
 **Files:** `internal/controller/health/*.go`, `cmd/proxy-checker/main.go`, tests

docs/requirements/traceability.md

@@ -32,7 +32,7 @@
 | FETCH-001 | 每个 Provider 有独立 requestInterval、maxInFlight、timeout 和 retry | 968-2394 | `provider/reconciler_test.go` |
 | FETCH-002 | 大量缺池信号合并为 singleflight/容量 1 通知 | 2067-2136, 8808-8849 | `coalesce.Signal` 与 100 并发通知测试 |
 | FETCH-003 | 错误使用指数退避和抖动，429 尊重 Retry-After | 1601-1831, 8808-8856 | `provider/reconciler_test.go` 与 `providerapi/http_adapter_test.go` |
-| FETCH-004 | Provider 获取由单逻辑 Leader 执行 | 1403-1580 | 单进程 Reconciler 已完成；Redis Leader 租约及多实例互斥测试待完成 |
+| FETCH-004 | Provider 获取由单逻辑 Leader 执行 | 1403-1580 | Redis Coordinator 已通过真实 Redis 双实例互斥、epoch 接管、全局间隔/在途 Permit 与 generation 重建测试；Provider Fleet/bootstrap 接线待完成 |
 | FETCH-005 | Empty 与 Error 分开；只有合法候选为零时 Empty++ | 8442-8529 | `fetch_result_test.go` 分类矩阵 |
 | FETCH-006 | 重复候选不当作 Empty，记录独立指标 | 8442-8480 | DuplicateOnly 分类与 Provider 测试 |
 | FETCH-007 | 模板限制响应大小、执行时间、函数集和外部访问 | 8808-8856 | `providerapi/template_parser_test.go` 输入、输出、候选、超时、递归与函数白名单测试 |
@@ -46,7 +46,7 @@
 | PROXY-002 | 唯一键包含 scheme、host、port、username、credentialVersion | 6655-6727, 8605-8678 | 去重单测 |
 | PROXY-003 | TTL 来源优先级明确并统一 UTC | 681-747, 8655-8678 | TTL 表驱动测试 |
 | CAP-001 | Gateway 分配使用 Reserved -> Active 原子转换 | 1203-1467, 8530-8597 | 固定 Max 下打包 CAS 与 1,000 并发不超卖已完成；动态降容和完整生命周期证据待完成 |
-| CAP-002 | 补池依据 Available Slots，不只看 Proxy 数量 | 1203-1402, 8530-8597 | TTL/状态/Active/Reserved 的 `AvailableSlots` 与 Reconciler 已测试；ownership、目标健康及 Gateway reserve 聚合待完成 |
+| CAP-002 | 补池依据 Available Slots，不只看 Proxy 数量 | 1203-1402, 8530-8597 | `AvailableSlots`、显式 minimum/target 水位、pending 槽位和迟滞 Reconciler 已测试；Worker Active/Reserved、ownership、目标健康及 Gateway reserve 运行时聚合待完成 |
 | CAP-003 | pool.maxSize 包括 FETCHED/CHECKING/AVAILABLE/SUSPECT/DRAINING 与 pending expected | 3001-3533, 6642-6680 | `FetchBudget` 100 并发额度预占测试 |
 | CAP-004 | TTL safety margin 内禁止新分配 | 173-220, 6728-6741 | 时钟测试 |
 | CAP-005 | 多 Worker 不在热路径访问 Redis 计数 | 1403-1467 | Gateway 包依赖审计、Snapshot/Dispatch 测试 |

progress.md

@@ -2,6 +2,21 @@
 
 ## 2026-07-30
 
+- 新增公用 Provider `Coordinator.RunLeader` / `LeaderSession` 深 seam 和独立
+  `redisprovider` Adapter；Redis Lua 原子维护 generation、epoch、Leader 租约、
+  全局 requestInterval 与带 TTL 的 maxInFlight Permit，异常时 fail-closed。
+- 真实 Redis 8.2 已验证两个 Controller 同 Upstream 只有一个 Leader、取消后
+  epoch 单调接管、跨实例请求限速/在途上限、Permit 幂等释放，以及 Redis 协调
+  状态丢失后使用新 generation 自动重建。
+- 新增显式 `refill.reconcileInterval/minimumAvailableSlots/targetAvailableSlots` 与
+  `fetch.estimatedIPsPerCall`；20 份示例、主配置、Compose/Kubernetes 配置均通过
+  严格解析和理论容量边界校验。
+- Pool Reconciler 已按并发槽位实现 minimum/target 迟滞并计入 pending 预估；
+  FetchBudget 只在没有 pending 请求时接受 Redis Managed 同步，消除 Upsert 与
+  Permit Complete 短窗口中的重复计数风险。
+- Provider Fleet、Worker Active/Reserved 容量汇总和 Controller bootstrap 接线
+  尚未完成，本轮不增加 51/73 的总验收计数。
+
 - 新增公用 `platform/metrics.NewHandler`，固定提供 `/livez`、`/readyz` 与
   `/metrics`；Readiness 失败只返回脱敏状态，不泄露底层存储错误。
 - Metrics 地址进入严格配置校验；Controller Runtime 支持 Metrics-only 和