// Package circuitbreaker provides a classic three-state breaker
// (Closed / Open / HalfOpen) that consumes success/failure signals
// and gates a caller's attempts. Designed to consume validator.Verdict
// signals via VerdictSink (a ValidatedTool decorator fires on every
// pre-commit Verdict).
//
// Decision flow:
//   Closed:   every Allow() returns nil; RecordFailure() increments a
//             counter; threshold breaches trip the breaker to Open.
//   Open:     Allow() returns ErrOpen until cooldown elapses, then the
//             breaker transitions to HalfOpen on the next Allow() call.
//   HalfOpen: the first Allow() returns nil (probe); subsequent Allow()
//             return ErrOpen until the probe reports back. Probe
//             RecordSuccess resets to Closed (failure counter zero);
//             RecordFailure trips back to Open (cooldown restarts).
//
// Deliberate omissions:
//   - No automatic retry / backoff: callers (the Agent) should observe
//     ErrOpen and replan, matching SQLCAS's maxRetries=0 default.
//   - No percentage-based threshold: a raw consecutive-failure count is
//     simpler to reason about and debug; platforms that want rate
//     windows wrap or replace this breaker.
//
// Package circuitbreaker 提供经典三态熔断器 (Closed / Open / HalfOpen),
// 消费成功 / 失败信号对调用方施加 gate. 设计上消费 validator.Verdict
// 信号经 VerdictSink (ValidatedTool decorator 每次 pre-commit Verdict
// 触发).
//
// 决策流:
//   Closed:   每次 Allow() 返 nil; RecordFailure() 累计计数; 破阈值
//             跳 Open.
//   Open:     Allow() 返 ErrOpen 直到 cooldown 过去; 下一次 Allow()
//             转 HalfOpen.
//   HalfOpen: 首次 Allow() 返 nil (试探), 后续 Allow() 返 ErrOpen 直到
//             试探回报. 试探 RecordSuccess 清零回 Closed; RecordFailure
//             回 Open (cooldown 重启).
//
// 刻意不做:
//   - 自动重试 / backoff: 调用方 (Agent) 应当看到 ErrOpen 重新 plan,
//     对齐 SQLCAS maxRetries=0 默认.
//   - 百分比阈值: 纯连续失败计数更易推理与调试; 要 rate 窗口的 platform
//     包装或替换本实现.
package circuitbreaker