fix(ratelimit): preserve bucket policy across runtime changes

[OnlineChef]

Problem

PR #44 was merged with a reproduced P1: existing token buckets refilled their entire elapsed interval using the newest policy passed to consume(). A low-to-high transition could over-admit, while a high-to-low transition could falsely deny.

Fix

• Store the governing policy on each principal and overflow bucket.
• Refill elapsed time under that stored policy before installing a new policy.
• Never mint tokens when burst capacity increases.
• Clamp existing balance when burst capacity decreases.
• Apply the same transition semantics to bounded shared overflow buckets.

Regression coverage

tests/ratelimit-policy-transition.test.ts covers:

• low → high rate transition;
• high → low rate transition;
• burst increase without free tokens;
• burst decrease with balance clamp;
• shared overflow-bucket transitions.

Merge gate

• Cross-platform CI green on exact head SHA
• Independent review of the transition semantics
• Re-run the PR feat(ratelimit): add admission limiter primitives #44 Greptile/T-Rex reproduction against this branch

This must land before PR #45 enables these primitives in runtime routes.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is enabled.}

Summary by CodeRabbit

• Bug Fixes

  • Improved rate-limit behavior when policies change, ensuring token refills use the correct prior rate.
  • Prevented policy updates from incorrectly creating extra burst capacity.
  • Clamped available tokens when burst limits decrease.
  • Improved consistency for shared overflow buckets during policy transitions.

• Tests

  • Added coverage for rate changes, burst-capacity adjustments, admission results, limits, remaining tokens, and rate-limit reasons.

Greptile Summary

This change preserves the policy governing a token bucket’s elapsed interval when runtime rate-limit settings change. It refills under the previous policy before applying the replacement policy, prevents burst increases from granting free requests, and clamps balances when burst capacity decreases. Focused runtime checks exercised low-to-high and high-to-low rate transitions, burst-capacity changes, and shared-overflow buckets; all tested paths behaved as intended.

Confidence Score: 5/5

T-Rex Logs

What T-Rex did

• Before the PR, ran the focused token-bucket transition runtime harness to verify the original low→high transition failure could be detected by the harness.
• After the PR, executed the transition tests and confirmed all five checks passed, with low→high and overflow transitions denied at 0 remaining and high→low preserving a token while burst reduction returned 1 remaining.
• Inspected the implementation around the transition sequence and confirmed the code path refills under the current policy, then clamps and installs the next policy, with no obvious new defect.

_{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "test(ratelimit): cover policy transition..." | Re-trigger Greptile}

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[coderabbitai]

📝 Walkthrough

Walkthrough

The token bucket now retains its active policy during elapsed-time calculations. Policy transitions refill under the previous policy, apply the new policy, and clamp tokens to the new burst capacity. Tests cover rate, burst, admission, and overflow behavior.

Changes

Token bucket policy transitions

Layer / File(s)	Summary
Policy state and bucket wiring src/ratelimit/token-bucket.ts:47-48, src/ratelimit/token-bucket.ts:96-99, src/ratelimit/token-bucket.ts:150-172	BucketState stores its governing RateLimitPolicy. samePolicy compares rate and burst settings. Principal and overflow buckets initialize the policy and use applyPolicy during consumption.
Policy transition behavior and validation src/ratelimit/token-bucket.ts:224-235, tests/ratelimit-policy-transition.test.ts:1-106	applyPolicy refills tokens with the previous policy, updates the stored policy, and clamps tokens to the new burst capacity. Tests cover rate changes, burst changes, and shared overflow buckets.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes preserving token-bucket policy behavior across runtime rate-limit changes.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/ratelimit-policy-transition

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}