feat: add isValid, fitsEncoded helpers and fix ceil overflow

Address audit findings:

1. Add isValid(q) to validate hand-wrapped Quant values against
   create() invariants (forgeable Quant via Quant.wrap).
2. Add fitsEncoded(q, encoded) as the decode-side counterpart of
   fits(), letting callers check encoded values before decoding.
3. Add CeilOverflow error and revert in ceil() when rounding up
   would wrap past type(uint256).max (was a silent overflow).
4. Label showcase stake() as intentionally lossy in NatSpec and
   README (floor-encoded dust stays in contract).
5. Bound fuzz test for decodeMax to valid encoded range. Update
   ceil fuzz test to exercise the overflow revert path instead
   of assuming it away.

Author: 0xferit

README.md

@@ -52,9 +52,11 @@ The `Quant` value type is a `uint16` with the following bit layout:
 | `q.encode(value, true)` | Same as `encode(value)`, but also reverts with `NotAligned` if `value` is not step-aligned. |
 | `q.decode(encoded)` | Decompresses `encoded` back to the original scale. Discarded bits are restored as zeros (lower bound). |
 | `q.decodeMax(encoded)` | Like `decode`, but fills discarded bits with ones (upper bound within the step). |
+| `q.isValid()` | True if `q` satisfies the invariants enforced by `create`. Use to validate hand-wrapped `Quant` values. |
 | `q.fits(value)` | True if `value` fits within the scheme's representable range. |
+| `q.fitsEncoded(encoded)` | True if `encoded` is within the valid range for decoding (`encoded < 2^encodedBitWidth`). |
 | `q.floor(value)` | Rounds `value` down to the nearest step boundary. |
-| `q.ceil(value)` | Rounds `value` up to the nearest step boundary. |
+| `q.ceil(value)` | Rounds `value` up to the nearest step boundary. Reverts with `CeilOverflow` when rounding up would exceed `type(uint256).max`. |
 | `q.remainder(value)` | Resolution lost if `value` were floor-encoded (`value mod stepSize`). |
 | `q.isAligned(value)` | True if `value` is step-aligned (no resolution loss on encode). |
 | `q.stepSize()` | Smallest non-zero value the scheme can represent (`2^discardedBitWidth`). |
@@ -66,6 +68,7 @@ The `Quant` value type is a `uint16` with the following bit layout:
 error BadConfig(uint256 discardedBitWidth, uint256 encodedBitWidth);
 error Overflow(uint256 value, uint256 max);
 error NotAligned(uint256 value, uint256 stepSize);
+error CeilOverflow(uint256 value);
 ```
 
 ### Solidity usage
@@ -161,8 +164,8 @@ This demonstrates where quantization creates real gas savings: fewer storage wri
 state layout.
 
 The staking showcase intentionally exercises the full API surface:
-- `stake()` uses `encode`.
-- `stakeExact()` uses `encode(value, true)`.
+- `stake()` uses floor encoding (`encode`). This is intentionally lossy: the remainder stays in the contract as unrecoverable dust.
+- `stakeExact()` uses strict encoding (`encode(value, true)`). Reverts if the value is not step-aligned, guaranteeing lossless round-trips.
 - `unstake()` uses `decode`.
 - `maxDeposit()`, `stakeRemainder()`, and `isStakeAligned()` expose
   `max`, `remainder`, and `isAligned` for frontend UX.

src/UintQuantizationLib.sol

@@ -34,6 +34,9 @@ error NotAligned(uint256 value, uint256 stepSize);
 /// @notice Thrown by `create` when the (discardedBitWidth, encodedBitWidth) pair is invalid.
 error BadConfig(uint256 discardedBitWidth, uint256 encodedBitWidth);
 
+/// @notice Thrown by `ceil` when rounding up would overflow uint256.
+error CeilOverflow(uint256 value);
+
 library UintQuantizationLib {
     string internal constant VERSION = "6.0.3";
 
@@ -145,26 +148,43 @@ library UintQuantizationLib {
         return remainder(q, value) == 0;
     }
 
+    /// @notice Returns true when `q` satisfies the invariants enforced by `create`.
+    ///         Use this to validate a `Quant` obtained via `Quant.wrap()` rather than `create()`.
+    function isValid(Quant q) internal pure returns (bool) {
+        uint256 d = discardedBitWidth(q);
+        uint256 e = encodedBitWidth(q);
+        return e > 0 && e < 256 && d + e <= 256;
+    }
+
     /// @notice Returns true when `value <= max(q)`.
     function fits(Quant q, uint256 value) internal pure returns (bool) {
         return value <= max(q);
     }
 
+    /// @notice Returns true when `encoded` is within the valid range for decoding.
+    ///         This is the decode-side counterpart of `fits()`.
+    function fitsEncoded(Quant q, uint256 encoded) internal pure returns (bool) {
+        return encoded < (uint256(1) << encodedBitWidth(q));
+    }
+
     /// @notice Rounds `value` down to the nearest step boundary (clears low `discardedBitWidth` bits).
     function floor(Quant q, uint256 value) internal pure returns (uint256) {
         return value & ~((uint256(1) << discardedBitWidth(q)) - 1);
     }
 
     /// @notice Rounds `value` up to the nearest step boundary. Returns `value` unchanged when
-    ///         discardedBitWidth is 0 or `value` is already aligned.
-    /// @dev    Callers must ensure `value + stepSize - 1 <= type(uint256).max` to avoid overflow
-    ///         on non-aligned inputs. This function does not perform that check.
+    ///         discardedBitWidth is 0 or `value` is already aligned. Reverts with `CeilOverflow`
+    ///         when rounding up would exceed `type(uint256).max`.
     function ceil(Quant q, uint256 value) internal pure returns (uint256) {
         uint256 s = discardedBitWidth(q);
         if (s == 0) return value;
         uint256 mask = (uint256(1) << s) - 1;
         if (value & mask == 0) return value;
-        return (value | mask) + 1;
+        unchecked {
+            uint256 ceiled = (value | mask) + 1;
+            if (ceiled == 0) revert CeilOverflow(value);
+            return ceiled;
+        }
     }
 }
 

src/showcase/ShowcaseSolidityFixtures.sol

@@ -67,6 +67,8 @@ contract QuantizedETHStakingShowcase {
         SCHEME = UintQuantizationLib.create(16, 96);
     }
 
+    /// @notice Floor-encodes msg.value. Intentionally lossy: the remainder (msg.value mod stepSize)
+    ///         stays in the contract as unrecoverable dust. Use `stakeExact` for lossless deposits.
     function stake() external payable {
         if (msg.value == 0) revert QuantizedETHStakingShowcase__ZeroAmount();
         uint96 encoded = uint96(SCHEME.encode(msg.value));

test/UintQuantizationLib.t.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.25;
 
 import {Test} from "forge-std/Test.sol";
-import {Quant, UintQuantizationLib, Overflow, NotAligned, BadConfig} from "src/UintQuantizationLib.sol";
+import {Quant, UintQuantizationLib, Overflow, NotAligned, BadConfig, CeilOverflow} from "src/UintQuantizationLib.sol";
 
 /// @notice Thin harness that exposes library functions via `using-for` so tests call them on
 ///         `Quant` values rather than through the library name directly.
@@ -51,10 +51,18 @@ contract QuantHarness {
         return q.isAligned(value);
     }
 
+    function isValid(Quant q) external pure returns (bool) {
+        return q.isValid();
+    }
+
     function fits(Quant q, uint256 value) external pure returns (bool) {
         return q.fits(value);
     }
 
+    function fitsEncoded(Quant q, uint256 encoded) external pure returns (bool) {
+        return q.fitsEncoded(encoded);
+    }
+
     function floor(Quant q, uint256 value) external pure returns (uint256) {
         return q.floor(value);
     }
@@ -201,7 +209,7 @@ contract UintQuantizationLibSmokeTest is Test {
     }
 
     // -------------------------------------------------------------------------
-    // Boundary: shift == 0 (identity / no compression)
+    // Boundary: discardedBitWidth == 0 (identity / no compression)
     // -------------------------------------------------------------------------
 
     function test_discardedBitWidth_zero_identity() public view {
@@ -280,6 +288,49 @@ contract UintQuantizationLibSmokeTest is Test {
         harness.encode(q, 2);
     }
 
+    // -------------------------------------------------------------------------
+    // isValid: create-produced vs hand-wrapped
+    // -------------------------------------------------------------------------
+
+    function test_isValid_createProduced() public view {
+        Quant q = harness.create(DISCARDED_8, ENCODED_8);
+        assertTrue(harness.isValid(q));
+    }
+
+    function test_isValid_handWrapped_invalid() public view {
+        // encodedBitWidth=0 (invalid: rejected by create)
+        assertFalse(harness.isValid(Quant.wrap(0)));
+        // discardedBitWidth=255, encodedBitWidth=255: sum=510 > 256
+        assertFalse(harness.isValid(Quant.wrap(uint16(0xFF00 | 0xFF))));
+    }
+
+    // -------------------------------------------------------------------------
+    // fitsEncoded: decode-side range check
+    // -------------------------------------------------------------------------
+
+    function test_fitsEncoded_true() public view {
+        Quant q = harness.create(DISCARDED_8, ENCODED_8);
+        // encodedBitWidth=8, so max encoded = 255
+        assertTrue(harness.fitsEncoded(q, 0));
+        assertTrue(harness.fitsEncoded(q, 255));
+    }
+
+    function test_fitsEncoded_false() public view {
+        Quant q = harness.create(DISCARDED_8, ENCODED_8);
+        assertFalse(harness.fitsEncoded(q, 256));
+    }
+
+    // -------------------------------------------------------------------------
+    // ceil: overflow revert
+    // -------------------------------------------------------------------------
+
+    function test_ceil_overflow_reverts() public {
+        Quant q = harness.create(DISCARDED_8, ENCODED_8);
+        // type(uint256).max is not aligned to 256; rounding up overflows
+        vm.expectRevert(abi.encodeWithSelector(CeilOverflow.selector, type(uint256).max));
+        harness.ceil(q, type(uint256).max);
+    }
+
     // -------------------------------------------------------------------------
     // Fuzz tests
     // -------------------------------------------------------------------------
@@ -303,6 +354,8 @@ contract UintQuantizationLibSmokeTest is Test {
     function testFuzz_decodeMax_ge_decode(uint8 discardedBitWidth_, uint8 encodedBitWidth_, uint256 encoded) public view {
         vm.assume(encodedBitWidth_ > 0 && uint256(discardedBitWidth_) + uint256(encodedBitWidth_) <= 256);
         Quant q = UintQuantizationLib.create(uint256(discardedBitWidth_), uint256(encodedBitWidth_));
+        // Bound to valid encoded range so the test exercises the documented domain.
+        encoded = bound(encoded, 0, (uint256(1) << harness.encodedBitWidth(q)) - 1);
         assertGe(harness.decodeMax(q, encoded), harness.decode(q, encoded));
     }
 
@@ -324,14 +377,18 @@ contract UintQuantizationLibSmokeTest is Test {
         assertEq(harness.fits(q, value), value <= harness.max(q));
     }
 
-    function testFuzz_ceil_ge_value(uint8 discardedBitWidth_, uint8 encodedBitWidth_, uint256 value) public view {
+    function testFuzz_ceil_ge_value(uint8 discardedBitWidth_, uint8 encodedBitWidth_, uint256 value) public {
         vm.assume(encodedBitWidth_ > 0 && uint256(discardedBitWidth_) + uint256(encodedBitWidth_) <= 256);
         Quant q = UintQuantizationLib.create(uint256(discardedBitWidth_), uint256(encodedBitWidth_));
         uint256 s = uint256(discardedBitWidth_);
         if (s > 0) {
             uint256 mask = (uint256(1) << s) - 1;
-            // Exclude values where (value | mask) + 1 would overflow uint256
-            vm.assume(value < type(uint256).max - mask);
+            if (value >= type(uint256).max - mask && value & mask != 0) {
+                // Overflow region: ceil should revert
+                vm.expectRevert(abi.encodeWithSelector(CeilOverflow.selector, value));
+                harness.ceil(q, value);
+                return;
+            }
         }
         assertGe(harness.ceil(q, value), value);
     }