refactor: document Quant validation rationale, demote extreme benchmark to log-only

Finding 1 (Quant forgeable): intentional design choice, now documented
in NatSpec. All functions are internal pure; the expected pattern is a
single create() at construction. Per-call validation would penalize
correct usage for a scenario that only arises from explicit wrap() misuse.

Finding 2 (extreme benchmark): the 80% savings threshold was a property
of the 12:1 slot ratio, not the library. Converted to log-only so it
serves as documentation rather than a misleading regression gate.
Real-life benchmark (>= 32%) remains as the CI gate.

Author: 0xferit

AGENTS.md

@@ -35,7 +35,7 @@ Production-style contracts for gas benchmarks only. Raw vs quantized pairs: `Raw
 ### Tests: `test/`
 
 - `UintQuantizationLib.t.sol`: `QuantHarness` exposes library via method-call syntax for external calls. `UintQuantizationLibSmokeTest` has concrete regression tests and fuzz tests. Fuzz parameters use `uint8` for discardedBitWidth/encodedBitWidth; use `bound()` over `vm.assume` for value-in-range constraints.
-- `showcase/ShowcaseGas.t.sol`: Asserts quantized paths save >= 32% (real-life) and >= 80% (extreme) gas vs raw on zero-to-nonzero writes.
+- `showcase/ShowcaseGas.t.sol`: Real-life benchmark asserts >= 32% gas savings vs raw on zero-to-nonzero writes. Extreme benchmark logs gas numbers for documentation (not a regression gate).
 
 ### Configuration
 

src/UintQuantizationLib.sol

@@ -26,6 +26,12 @@ pragma solidity ^0.8.25;
  *         **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.
+ *
+ *         Design note: library functions do not validate `q` on every call. All functions are
+ *         `internal pure` and run inside the integrator's contract; the expected pattern is a
+ *         single `create()` at construction time (typically `immutable`). Adding per-call
+ *         validation would penalize the correct-usage path for a scenario that only arises
+ *         from explicit `Quant.wrap()` misuse.
  */
 type Quant is uint16;
 

test/showcase/ShowcaseGas.t.sol

@@ -20,7 +20,6 @@ contract ShowcaseGasTest is Test {
     uint256 internal constant EXT_LANE_MAX = (uint256(1) << EXT_WIDTH) - 1;
 
     uint256 internal constant MIN_REAL_SAVINGS_BPS = 3_200; // >=32%
-    uint256 internal constant MIN_EXTREME_SAVINGS_BPS = 8_000; // >=80%
 
     uint256 internal constant REAL_STAKE_STRICT = uint256(2_500_000) << REAL_SHIFT;
     uint256 internal constant REAL_STAKE_STRICT_ALT = uint256(2_750_000) << REAL_SHIFT;
@@ -69,15 +68,18 @@ contract ShowcaseGasTest is Test {
         assertGe(_savingsBps(rawGas, strictGas), MIN_REAL_SAVINGS_BPS);
     }
 
-    function test_gas_extreme_solidity_zero_to_nonzero_savings_ge_target() public {
+    /// @notice Logs extreme-packing gas numbers for documentation. Not a regression gate:
+    ///         the savings are a property of the 12:1 slot ratio, not the library's efficiency.
+    function test_gas_extreme_solidity_zero_to_nonzero_logs() public {
         uint256 rawGas = _measureSolidityExtremeRaw();
         uint256 floorGas = _measureSolidityExtremeQuantFloor();
         uint256 strictGas = _measureSolidityExtremeQuantStrict();
 
-        assertGt(rawGas, floorGas);
-        assertGt(rawGas, strictGas);
-        assertGe(_savingsBps(rawGas, floorGas), MIN_EXTREME_SAVINGS_BPS);
-        assertGe(_savingsBps(rawGas, strictGas), MIN_EXTREME_SAVINGS_BPS);
+        emit log_named_uint("extreme raw gas", rawGas);
+        emit log_named_uint("extreme floor gas", floorGas);
+        emit log_named_uint("extreme strict gas", strictGas);
+        emit log_named_uint("extreme floor savings bps", _savingsBps(rawGas, floorGas));
+        emit log_named_uint("extreme strict savings bps", _savingsBps(rawGas, strictGas));
     }
 
     function test_showcase_inputs_fit_lanes() public pure {