Reject a negative stored level and negative timestamps

[thedavidmeister]

Refs #115

Delivers the "prevent negatives" half of what #116 left open. The directed rounding half is not delivered; see below.

What changed

• checkFillableDomain now also refuses a negative stored level, a negative stored timestamp and a negative timestamp argument, at levelAt, headroomAt and fill, before the amount is looked at.
• New errors: LeakyBucketNegativeLevel(Float level) and LeakyBucketNegativeTimestamp(Float timestamp). The second serves both the stored and the supplied timestamp and carries the offending value.
• mutants.toml named .mutation-test/suite.sh, which is not tracked; it now names the tracked .mutation-test/check.sh. M09, M10 and M16-M18 are retargeted at the new spelling; M20-M22 are added.

Directed rounding: not delivered

The ruling on #115 is that the level is never understated and the drain never overstated. rain-math-float 0.2.4 cannot express that: its own docs say "There is no concept of rounding modes", and add, sub and mul report no remainder. Measured against 0.2.4 with a throwaway test (not committed):

Expression	Result	True value	Direction
1 + 1e-70	exactly 1	above 1	down
1 - 1e-70	0.99...9 (67 nines)	70 nines	down
1 - 1e-80	exactly 1	below 1	up
(1e66+1)^2	1e132 + 2e66	1e132 + 2e66 + 1	down

Everything truncates toward zero, at three sites: the exponent alignment in LibDecimalFloatImplementation.add (signedCoefficientB /= 10 ** diff, with the smaller operand dropped whole past ADD_MAX_EXPONENT_DIFF), mulDiv in mul, and the coefficient shrink in packLossy. For the bucket, elapsed * leakRate already rounds the safe way, level + amount rounds the unsafe way, and level - drain goes either way depending on the exponent gap.

What the float library would need to expose: add, sub and mul variants that take a rounding direction, or that return a lossless flag covering alignment, mulDiv and packing together, plus a one-ulp step up and down. Nothing here works around the gap.

QA

• Discriminating tests: testEntryPointsRejectANegativeLevel, testEntryPointsRejectANegativeStoredTimestamp, testEntryPointsRejectANegativeTimestamp, testANegativeLevelCannotBuyHeadroomAboveCapacity, testANegativeFractionIsRefusedLikeAnyNegative, and two new selectors in testErrorSelectorsArePinnedToTheirSignatures - on base they do not compile (the errors do not exist); with the errors declared and a check dropped they fail (M20-M22 below).
• Mutations applied: mutation-probe over mutants.toml M01-M22. M20 if (bucket.level.lt(0)) -> if (false), M21 if (bucket.timestamp.lt(0)) -> if (false), M22 if (timestamp.lt(0)) -> if (false): all three SURVIVED the pre-existing 58-test suite at f954fe8 (19/22), and are KILLED by testANegativeFractionIsRefusedLikeAnyNegative (M20 also by testANegativeLevelCannotBuyHeadroomAboveCapacity) at 25e49b1: 22/22 killed, 0 no-run, 0 harness errors, 63 tests; re-probed 22/22 at 4e60fed after a lint-only test fix.
• Oracle: issue Move the bucket to Rain Floats, and reject negative values #115 "The library itself should reject negative values", applied to every Float the library accepts; expected errors are named from the input sign, not from the implementation.
• Category check: issue asks (A) directed rounding per the owner's ruling, (B) reject negatives; covered B only / Refs because A needs rounding-direction arithmetic that rain-math-float 0.2.4 does not expose.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 40 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 1ad9af10-a634-4c5f-a035-82b3ac3bd3ae

📥 Commits

Reviewing files that changed from the base of the PR and between b6c639f and 1d66ac6.

📒 Files selected for processing (5)

• README.md
• audit/mutation-test-scans.json
• mutants.toml
• src/lib/LibLeakyBucket.sol
• test/src/lib/LibLeakyBucket.t.sol

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[github-actions]

@coderabbitai assess this PR size classification for the totality of the PR with the following criterias and report it in your comment:

S/M/L PR Classification Guidelines:

This guide helps classify merged pull requests by effort and complexity rather than just line count. The goal is to assess the difficulty and scope of changes after they have been completed.

Small (S)

Characteristics:

• Simple bug fixes, typos, or minor refactoring
• Single-purpose changes affecting 1-2 files
• Documentation updates
• Configuration tweaks
• Changes that require minimal context to review

Review Effort: Would have taken 5-10 minutes

Examples:

• Fix typo in variable name
• Update README with new instructions
• Adjust configuration values
• Simple one-line bug fixes
• Import statement cleanup

Medium (M)

Characteristics:

• Feature additions or enhancements
• Refactoring that touches multiple files but maintains existing behavior
• Breaking changes with backward compatibility
• Changes requiring some domain knowledge to review

Review Effort: Would have taken 15-30 minutes

Examples:

• Add new feature or component
• Refactor common utility functions
• Update dependencies with minor breaking changes
• Add new component with tests
• Performance optimizations
• More complex bug fixes

Large (L)

Characteristics:

• Major feature implementations
• Breaking changes or API redesigns
• Complex refactoring across multiple modules
• New architectural patterns or significant design changes
• Changes requiring deep context and multiple review rounds

Review Effort: Would have taken 45+ minutes

Examples:

• Complete new feature with frontend/backend changes
• Protocol upgrades or breaking changes
• Major architectural refactoring
• Framework or technology upgrades

Additional Factors to Consider

When deciding between sizes, also consider:

• Test coverage impact: More comprehensive test changes lean toward larger classification
• Risk level: Changes to critical systems bump up a size category
• Team familiarity: Novel patterns or technologies increase complexity

Notes:

• the assessment must be for the totality of the PR, that means comparing the base branch to the last commit of the PR
• the assessment output must be exactly one of: S, M or L (single-line comment) in format of: SIZE={S/M/L}
• do not include any additional text, only the size classification
• your assessment comment must not include tips or additional sections
• do NOT tag me or anyone else on your comment

[linear]

RAI-2879