docs: document failure-domain sharing and half-open throttle semantics

hoglet.go

@@ -201,6 +201,11 @@ func (s stateObserver) Observe(failure bool) {
 // The returned function calls the wrapped function if the circuit is closed and returns its result.
 // If the circuit is open, it returns [ErrCircuitOpen].
 //
+// A single [Circuit] may wrap multiple functions of differing signatures. Those functions then share a single failure
+// domain: state and failure rate are shared, so a failure in one opens the circuit for all of them. Wrap functions that
+// share a downstream dependency (e.g. several methods against the same backend) on one circuit; use separate circuits
+// for independent dependencies.
+//
 // The wrapped function is called synchronously, but possible context errors are recorded as soon as they occur. This
 // ensures the circuit opens quickly, even if the wrapped function blocks.
 //

options.go

@@ -23,6 +23,11 @@ func (f optionFunc) apply(o *options) error {
 // Breakers may require or constrain this value: [EWMABreaker] requires a non-zero delay (it cannot recover without one),
 // while [SlidingWindowBreaker] defaults it to its window size and rejects a value exceeding it. Such violations are
 // reported as errors by [NewCircuit].
+//
+// Note: the half-open throttle is launch-rate based, not in-flight based. Each probe resets the delay, so a new probe
+// is admitted roughly every delay regardless of whether the previous one has returned. Against a slow (rather than
+// failing) dependency this can result in multiple concurrent in-flight probes. To bound the number of concurrent
+// probes instead, compose a [ConcurrencyLimiter] middleware via [WithBreakerMiddleware].
 func WithHalfOpenDelay(delay time.Duration) Option {
 	return optionFunc(func(o *options) error {
 		o.halfOpenDelay = delay