📝 docs(limiter): add utilization-adaptive limits design

[sodre]

Summary

• Adds docs/plans/2026-09-14-adaptive-limits-design.md, an evaluation of how ✨ Support utilization-based adaptive rate limits #223 (utilization-adaptive limits) could be built on top of the ✨ Support time-based dynamic rate limits with scheduling #222 scheduled-limits machinery
• Records twelve settled decisions, each with rejected alternatives:
  • ✨ Support utilization-based adaptive rate limits #223 is not evaluated at acquire time. A controller adjusts buckets and the refillers enforce
  • The aggregator becomes required, but only for adaptive limits. The aggregator senses usage and a scheduled controller acts on it
  • When usage data is stale, the controller never loosens: factor = min(current, 1x)
  • The controller uses a target band that raises slowly and lowers quickly, replacing 1 / utilization
  • Opt-in is a max_scale multiplier on Limit. min_scale is designed but not shipped
  • Fair-share policies are pluggable, with exactly one active per (resource, limit)
  • The factor lives in its own bucket attribute af and is never written into cp/ra. It is written only when it changes. Bucket creators stamp it and the aggregator repairs it
  • Cascade counts only non-cascading buckets, and parent and child scale independently
  • Every surface reports the effective limit (base x factor)
• Includes storage and writer-table additions, cost estimates, open questions for the implementation plan, known limitations and a testing sketch
• Docs only, with no code changes, and the work is not scheduled. docs/plans/ is excluded from the MkDocs build (exclude_docs)

Test plan

• Review the design doc for consistency with the ✨ Support time-based dynamic rate limits with scheduling #222 scheduled-limits design
• Confirm the writer-table additions (af) do not conflict with the existing writer table in CLAUDE.md
• Docs CI passes

Refs #223

🤖 Generated with Claude Code

https://claude.ai/code/session_019J8sTVc3atEwMyWhfrdznc

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.63%. Comparing base (268ca2c) to head (efc3ba1).
⚠️ Report is 4 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #520      +/-   ##
==========================================
- Coverage   93.83%   90.63%   -3.21%     
==========================================
  Files          49       49              
  Lines       10127    11178    +1051     
==========================================
+ Hits         9503    10131     +628     
- Misses        624     1047     +423     

Flag	Coverage Δ
doctest	30.73% <ø> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.