Merge pull request #92 from 0xferit/claude/issue-90-20260313-1816

refactor: replace encodeLossless with encode(value, precise) overload

Author: 0xferit

src/UintQuantizationLib.sol

@@ -28,7 +28,7 @@ type Quant is uint16;
 /// @notice Thrown when a value exceeds the maximum representable by the scheme.
 error Overflow(uint256 value, uint256 max);
 
-/// @notice Thrown by `encodeLossless` when a value is not aligned to the step size.
+/// @notice Thrown by `encode` (precise mode) when a value is not aligned to the step size.
 error NotAligned(uint256 value, uint256 stepSize);
 
 /// @notice Thrown by `create` when the (shift, targetBits) pair is invalid.
@@ -92,13 +92,16 @@ library UintQuantizationLib {
         return value >> shift(q);
     }
 
-    /// @notice Strict mode: reverts if value exceeds max(q) or is not step-aligned.
-    function encodeLossless(Quant q, uint256 value) internal pure returns (uint256) {
+    /// @notice Encodes `value`. When `precise` is true, reverts if value is not step-aligned.
+    ///         Always reverts if value exceeds `max(q)`.
+    function encode(Quant q, uint256 value, bool precise) internal pure returns (uint256) {
         uint256 m = max(q);
         if (value > m) revert Overflow(value, m);
         uint256 s = shift(q);
-        uint256 step = uint256(1) << s;
-        if (value & (step - 1) != 0) revert NotAligned(value, step);
+        if (precise) {
+            uint256 step = uint256(1) << s;
+            if (value & (step - 1) != 0) revert NotAligned(value, step);
+        }
         return value >> s;
     }
 
@@ -109,7 +112,7 @@ library UintQuantizationLib {
     /// @notice Left-shifts `encoded` by shift, restoring discarded bits as zeros (lower bound).
     /// @dev    The caller must ensure `encoded < 2**targetBits(q)`. Passing a larger value
     ///         produces a result that may silently wrap or exceed the scheme's representable range.
-    ///         Values returned by `encode` and `encodeLossless` always satisfy this constraint.
+    ///         Values returned by `encode` always satisfy this constraint.
     function decode(Quant q, uint256 encoded) internal pure returns (uint256) {
         unchecked {
             return encoded << shift(q);

src/showcase/ShowcaseSolidityFixtures.sol

@@ -80,7 +80,7 @@ contract QuantizedETHStakingShowcase {
 
     function stakeExact() external payable {
         if (msg.value == 0) revert QuantizedETHStakingShowcase__ZeroAmount();
-        uint96 encoded = uint96(SCHEME.encodeLossless(msg.value));
+        uint96 encoded = uint96(SCHEME.encode(msg.value, true));
         stakes[msg.sender] = UserStake({
             amount: encoded,
             stakedAt: uint64(block.timestamp),
@@ -165,7 +165,7 @@ contract QuantizedExtremePackingShowcase {
     function setExtremeStrict(uint256[12] calldata values) external {
         uint256 p;
         for (uint256 i; i < LANES; ++i) {
-            uint256 lane = SCHEME.encodeLossless(values[i]);
+            uint256 lane = SCHEME.encode(values[i], true);
             p |= lane << (i * 20);
         }
         packedExtreme = p;

test/UintQuantizationLib.t.sol

@@ -31,8 +31,8 @@ contract QuantHarness {
         return q.encode(value);
     }
 
-    function encodeLossless(Quant q, uint256 value) external pure returns (uint256) {
-        return q.encodeLossless(value);
+    function encode(Quant q, uint256 value, bool precise) external pure returns (uint256) {
+        return q.encode(value, precise);
     }
 
     function decode(Quant q, uint256 encoded) external pure returns (uint256) {
@@ -113,23 +113,30 @@ contract UintQuantizationLibSmokeTest is Test {
     }
 
     // -------------------------------------------------------------------------
-    // encodeLossless: overflow and alignment reverts
+    // encode (precise=true): overflow and alignment reverts
     // -------------------------------------------------------------------------
 
-    function test_encodeLossless_overflow_reverts() public {
+    function test_encodePrecise_overflow_reverts() public {
         Quant q = harness.create(SHIFT_8, BITS_8);
         uint256 m = harness.max(q);
         uint256 value = m + 1;
         vm.expectRevert(abi.encodeWithSelector(Overflow.selector, value, m));
-        harness.encodeLossless(q, value);
+        harness.encode(q, value, true);
     }
 
-    function test_encodeLossless_notAligned_reverts() public {
+    function test_encodePrecise_notAligned_reverts() public {
         Quant q = harness.create(SHIFT_8, BITS_8);
         uint256 step = harness.stepSize(q); // 256
         uint256 value = step + 1; // 257, not aligned
         vm.expectRevert(abi.encodeWithSelector(NotAligned.selector, value, step));
-        harness.encodeLossless(q, value);
+        harness.encode(q, value, true);
+    }
+
+    function test_encodePrecise_aligned_succeeds() public view {
+        Quant q = harness.create(SHIFT_8, BITS_8);
+        uint256 step = harness.stepSize(q); // 256
+        // 256 is aligned: encode(256, true) == 1
+        assertEq(harness.encode(q, step, true), 1);
     }
 
     // -------------------------------------------------------------------------