feat: make decode/decodeMax checked by default, add unchecked variants

decode() and decodeMax() now revert with Overflow when encoded is
out of range, matching encode()'s safe-by-default behavior.

Added decodeUnchecked() and decodeMaxUnchecked() for gas-optimized
paths where encoded values are known valid (e.g. from encode()).
Showcase contracts switched to unchecked variants since their values
always come from encode().

Also: strengthened Quant NatSpec warning against Quant.wrap(),
added lossy-deposit warning to README StakingVault example,
consolidated empty CHANGELOG entries from pipeline iteration.

Author: 0xferit

CHANGELOG.md

@@ -6,23 +6,9 @@
 
 * add isValid, fitsEncoded helpers and fix ceil overflow ([903287c](https://github.com/0xferit/uint-quantization-lib/commit/903287c19bd7b97b4d8f096a1dce5479638805f5))
 
-## [6.0.3](https://github.com/0xferit/uint-quantization-lib/compare/v6.0.2...v6.0.3) (2026-03-13)
+## 1.0.1 through 6.0.3 (2026-03-13)
 
-## [6.0.2](https://github.com/0xferit/uint-quantization-lib/compare/v6.0.1...v6.0.2) (2026-03-13)
-
-## [6.0.1](https://github.com/0xferit/uint-quantization-lib/compare/v6.0.0...v6.0.1) (2026-03-13)
-
-## [6.0.0](https://github.com/0xferit/uint-quantization-lib/compare/v5.0.0...v6.0.0) (2026-03-13)
-
-## [5.0.0](https://github.com/0xferit/uint-quantization-lib/compare/v4.0.0...v5.0.0) (2026-03-13)
-
-## [4.0.0](https://github.com/0xferit/uint-quantization-lib/compare/v3.0.0...v4.0.0) (2026-03-13)
-
-## [3.0.0](https://github.com/0xferit/uint-quantization-lib/compare/v2.0.0...v3.0.0) (2026-03-13)
-
-## [2.0.0](https://github.com/0xferit/uint-quantization-lib/compare/v1.0.1...v2.0.0) (2026-03-13)
-
-## [1.0.1](https://github.com/0xferit/uint-quantization-lib/compare/v1.0.0...v1.0.1) (2026-03-13)
+Versions 1.0.1 through 6.0.3 were created by release pipeline iteration during initial CI setup. The library was renamed from `shift`/`targetBits` to `discardedBitWidth`/`encodedBitWidth` (breaking API change, hence the major bumps). No functional changes between these versions beyond the rename and CI fixes. See [v1.0.0...v6.0.3](https://github.com/0xferit/uint-quantization-lib/compare/v1.0.0...v6.0.3) for the full diff.
 
 ## 1.0.0 (2026-03-13)
 

README.md

@@ -48,10 +48,12 @@ The `Quant` value type is a `uint16` with the following bit layout:
 | `UintQuantizationLib.create(discardedBitWidth, encodedBitWidth)` | Creates a `Quant` scheme. Reverts with `BadConfig` on invalid parameters. |
 | `q.discardedBitWidth()` | Number of low bits discarded during encoding (set at creation). |
 | `q.encodedBitWidth()` | Bit-width of the encoded value (set at creation). |
-| `q.encode(value)` | Compresses `value` by discarding the low bits (floor). Reverts with `Overflow` if `value > max(q)`. |
+| `q.encode(value)` | Quantizes `value` by discarding the low bits (floor). Reverts with `Overflow` if `value > max(q)`. |
 | `q.encode(value, true)` | Same as `encode(value)`, but also reverts with `NotAligned` if `value` is not step-aligned. |
-| `q.decode(encoded)` | Restores `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.decode(encoded)` | Restores `encoded` back to the original scale (lower bound). Reverts with `Overflow` if `encoded` is out of range. |
+| `q.decodeMax(encoded)` | Like `decode`, but fills discarded bits with ones (upper bound). Reverts with `Overflow` if out of range. |
+| `q.decodeUnchecked(encoded)` | Gas-optimized `decode` without bounds check. Use when `encoded` is known valid (e.g., from `encode`). |
+| `q.decodeMaxUnchecked(encoded)` | Gas-optimized `decodeMax` without bounds check. |
 | `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`). |
@@ -82,6 +84,8 @@ contract StakingVault {
     mapping(address => uint96) internal stakes;
 
     /// Floor-encodes msg.value and stores the quantized amount.
+    /// Lossy: the remainder (msg.value mod stepSize) is not tracked.
+    /// Use `stakeExact` for lossless deposits.
     function stake() external payable {
         require(SCHEME.fits(msg.value), "amount exceeds scheme max");
         stakes[msg.sender] = uint96(SCHEME.encode(msg.value));

src/UintQuantizationLib.sol

@@ -22,6 +22,10 @@ pragma solidity ^0.8.25;
  *         stored   = uint24(SCHEME.encode(value));
  *         restored = SCHEME.decode(stored);
  *         ```
+ *
+ *         **Important:** Always construct `Quant` values via `create()`. Using `Quant.wrap()`
+ *         directly bypasses validation and produces undefined behavior in all library functions.
+ *         Use `isValid()` to check a `Quant` of unknown origin.
  */
 type Quant is uint16;
 
@@ -116,18 +120,36 @@ library UintQuantizationLib {
     // -------------------------------------------------------------------------
 
     /// @notice Left-shifts `encoded` by discardedBitWidth, restoring discarded bits as zeros (lower bound).
-    /// @dev    The caller must ensure `encoded < 2**encodedBitWidth(q)`. Passing a larger value
-    ///         produces a result that may silently wrap or exceed the scheme's representable range.
-    ///         Values returned by `encode` always satisfy this constraint.
+    ///         Reverts with `Overflow` when `encoded >= 2**encodedBitWidth(q)`.
     function decode(Quant q, uint256 encoded) internal pure returns (uint256) {
+        uint256 e = encodedBitWidth(q);
+        if (encoded >= (uint256(1) << e)) revert Overflow(encoded, (uint256(1) << e) - 1);
         unchecked {
             return encoded << discardedBitWidth(q);
         }
     }
 
     /// @notice Like `decode` but fills the discarded bits with ones (upper bound within the step).
-    /// @dev    Same precondition as `decode`: `encoded` must be less than `2**encodedBitWidth(q)`.
+    ///         Reverts with `Overflow` when `encoded >= 2**encodedBitWidth(q)`.
     function decodeMax(Quant q, uint256 encoded) internal pure returns (uint256) {
+        uint256 e = encodedBitWidth(q);
+        if (encoded >= (uint256(1) << e)) revert Overflow(encoded, (uint256(1) << e) - 1);
+        unchecked {
+            uint256 s = discardedBitWidth(q);
+            return (encoded << s) | ((uint256(1) << s) - 1);
+        }
+    }
+
+    /// @notice Unchecked `decode`: no bounds check on `encoded`. Use when `encoded` is known to be
+    ///         valid (e.g., returned by `encode`). Passing an out-of-range value wraps silently.
+    function decodeUnchecked(Quant q, uint256 encoded) internal pure returns (uint256) {
+        unchecked {
+            return encoded << discardedBitWidth(q);
+        }
+    }
+
+    /// @notice Unchecked `decodeMax`: no bounds check on `encoded`. Same precondition as `decodeUnchecked`.
+    function decodeMaxUnchecked(Quant q, uint256 encoded) internal pure returns (uint256) {
         unchecked {
             uint256 s = discardedBitWidth(q);
             return (encoded << s) | ((uint256(1) << s) - 1);

src/showcase/ShowcaseSolidityFixtures.sol

@@ -95,7 +95,7 @@ contract QuantizedETHStakingShowcase {
         UserStake memory s = stakes[msg.sender];
         if (!s.active) revert QuantizedETHStakingShowcase__NoStake();
 
-        uint256 amount = SCHEME.decode(s.amount);
+        uint256 amount = SCHEME.decodeUnchecked(s.amount);
         delete stakes[msg.sender];
 
         (bool ok,) = msg.sender.call{value: amount}("");
@@ -112,7 +112,7 @@ contract QuantizedETHStakingShowcase {
     }
 
     function getStake(address user) external view returns (uint256) {
-        return SCHEME.decode(stakes[user].amount);
+        return SCHEME.decodeUnchecked(stakes[user].amount);
     }
 
     function maxDeposit() external view returns (uint256) {
@@ -183,7 +183,7 @@ contract QuantizedExtremePackingShowcase {
     function decodeExtremeFloor() external view returns (uint256[12] memory values) {
         uint256 p = packedExtreme;
         for (uint256 i; i < LANES; ++i) {
-            values[i] = SCHEME.decode((p >> (i * 20)) & LANE_MASK);
+            values[i] = SCHEME.decodeUnchecked((p >> (i * 20)) & LANE_MASK);
         }
     }
 }

test/UintQuantizationLib.t.sol

@@ -43,6 +43,14 @@ contract QuantHarness {
         return q.decodeMax(encoded);
     }
 
+    function decodeUnchecked(Quant q, uint256 encoded) external pure returns (uint256) {
+        return q.decodeUnchecked(encoded);
+    }
+
+    function decodeMaxUnchecked(Quant q, uint256 encoded) external pure returns (uint256) {
+        return q.decodeMaxUnchecked(encoded);
+    }
+
     function remainder(Quant q, uint256 value) external pure returns (uint256) {
         return q.remainder(value);
     }
@@ -320,6 +328,34 @@ contract UintQuantizationLibSmokeTest is Test {
         assertFalse(harness.fitsEncoded(q, 256));
     }
 
+    // -------------------------------------------------------------------------
+    // decode: checked revert on oversized encoded
+    // -------------------------------------------------------------------------
+
+    function test_decode_oversized_reverts() public {
+        Quant q = harness.create(DISCARDED_8, ENCODED_8);
+        // encodedBitWidth=8, so max encoded = 255; 256 is out of range
+        vm.expectRevert(abi.encodeWithSelector(Overflow.selector, uint256(256), uint256(255)));
+        harness.decode(q, 256);
+    }
+
+    function test_decodeMax_oversized_reverts() public {
+        Quant q = harness.create(DISCARDED_8, ENCODED_8);
+        vm.expectRevert(abi.encodeWithSelector(Overflow.selector, uint256(256), uint256(255)));
+        harness.decodeMax(q, 256);
+    }
+
+    function test_decodeUnchecked_valid() public view {
+        Quant q = harness.create(DISCARDED_8, ENCODED_8);
+        // Same result as checked decode for valid input
+        assertEq(harness.decodeUnchecked(q, 3), harness.decode(q, 3));
+    }
+
+    function test_decodeMaxUnchecked_valid() public view {
+        Quant q = harness.create(DISCARDED_8, ENCODED_8);
+        assertEq(harness.decodeMaxUnchecked(q, 3), harness.decodeMax(q, 3));
+    }
+
     // -------------------------------------------------------------------------
     // ceil: overflow revert
     // -------------------------------------------------------------------------