fix: various comments addressed

- reorder param structs statics-first (ABI change)
- inline _positionAmounts into the sweep step
- reject pools whose hook carries a returns-delta permission upfront
  (UnsupportedHookPermissions) instead of documenting them only
- move the trim cap into getLiquidityToFree with a forward round-down
  pre-check, making the previously documented far-edge overflow in the
  inverse structurally unreachable

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mgretzke

src/SwapAndAdd.sol

@@ -2,6 +2,7 @@
 pragma solidity 0.8.26;
 
 import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+import {IHooks} from "@uniswap/v4-core/src/interfaces/IHooks.sol";
 import {ERC20} from "solmate/src/tokens/ERC20.sol";
 import {ERC721} from "solmate/src/tokens/ERC721.sol";
 import {SafeTransferLib} from "solmate/src/utils/SafeTransferLib.sol";
@@ -13,6 +14,7 @@ import {SafeCast} from "@uniswap/v4-core/src/libraries/SafeCast.sol";
 import {StateLibrary} from "@uniswap/v4-core/src/libraries/StateLibrary.sol";
 import {TransientStateLibrary} from "@uniswap/v4-core/src/libraries/TransientStateLibrary.sol";
 import {TickMath} from "@uniswap/v4-core/src/libraries/TickMath.sol";
+import {Hooks} from "@uniswap/v4-core/src/libraries/Hooks.sol";
 
 import {IAllowanceTransfer} from "permit2/src/interfaces/IAllowanceTransfer.sol";
 
@@ -47,7 +49,13 @@ contract SwapAndAdd is ISwapAndAdd, SafeCallback, DeltaResolver, Permit2Forwarde
     using PoolIdLibrary for PoolKey;
     using PositionInfoLibrary for PositionInfo;
     using SafeCast for uint256;
+    using Hooks for IHooks;
 
+    /// @dev Hook permissions that let a hook alter this contract's settlement deltas, breaking the
+    ///      conservation accounting the reconcile relies on. Pools carrying any of them are rejected.
+    uint160 private constant UNSUPPORTED_HOOK_FLAGS = Hooks.BEFORE_SWAP_RETURNS_DELTA_FLAG
+        | Hooks.AFTER_SWAP_RETURNS_DELTA_FLAG | Hooks.AFTER_ADD_LIQUIDITY_RETURNS_DELTA_FLAG
+        | Hooks.AFTER_REMOVE_LIQUIDITY_RETURNS_DELTA_FLAG;
     /// @dev Standing Permit2 allowance expiration timestamp.
     uint48 private constant ALLOWANCE_EXPIRATION = type(uint48).max;
     /// @dev Universal Router command to sweep unspent native ETH.
@@ -287,6 +295,10 @@ contract SwapAndAdd is ISwapAndAdd, SafeCallback, DeltaResolver, Permit2Forwarde
         internal
         returns (uint256 tokenId, uint128 liquidity, uint256 amount0, uint256 amount1)
     {
+        // Pure bitmask on the hook address; a benignly-behaving hook with the permission is still rejected —
+        // the boundary is the capability, not observed behavior.
+        if (cp.key.hooks.hasPermission(UNSUPPORTED_HOOK_FLAGS)) revert UnsupportedHookPermissions(cp.key.hooks);
+
         _ensureApproved(cp.key.currency0);
         _ensureApproved(cp.key.currency1);
 
@@ -319,8 +331,9 @@ contract SwapAndAdd is ISwapAndAdd, SafeCallback, DeltaResolver, Permit2Forwarde
         // 4. Slippage Floor: Enforce minimum liquidity threshold on final post-trim position.
         if (liquidity < cp.minLiquidity) revert InsufficientLiquidity(cp.minLiquidity, liquidity);
 
-        // 5. Sweep: Calculate final token composition and sweep leftover dust in both pool tokens to recipient.
-        (amount0, amount1) = _positionAmounts(cp, liquidity, sqrtLower, sqrtUpper);
+        // 5. Sweep: Calculate final position token amounts at live price and sweep leftover dust to recipient.
+        (uint160 sqrtPriceX96,,,) = poolManager.getSlot0(cp.key.toId());
+        (amount0, amount1) = SwapAndAddMath.getAmountsForLiquidity(sqrtPriceX96, sqrtLower, sqrtUpper, liquidity);
         _sweep(cp.key.currency0, cp.recipient);
         _sweep(cp.key.currency1, cp.recipient);
     }
@@ -412,23 +425,11 @@ contract SwapAndAdd is ISwapAndAdd, SafeCallback, DeltaResolver, Permit2Forwarde
     ) internal returns (uint128 dl) {
         // Fresh price read: the reconcile swap (or a hook) moved the price since sizing.
         (uint160 sqrtPriceX96,,,) = poolManager.getSlot0(cp.key.toId());
-        uint256 liquidityToFree =
-            SwapAndAddMath.getLiquidityToFree(sqrtPriceX96, sqrtLower, sqrtUpper, deficitIsCurrency1, amountOut);
-        // Cap trim at the liquidity added in this transaction.
-        dl = liquidityToFree >= lopt ? lopt : uint128(liquidityToFree);
+        // Capped at `lopt`, the liquidity added in this transaction.
+        dl = SwapAndAddMath.getLiquidityToFree(sqrtPriceX96, sqrtLower, sqrtUpper, deficitIsCurrency1, amountOut, lopt);
         _decrease(cp.key, tokenId, dl, cp.hookData);
     }
 
-    /// @dev Calculates final position token amounts at the current pool price.
-    function _positionAmounts(CoreParams memory cp, uint128 liquidity, uint160 sqrtLower, uint160 sqrtUpper)
-        internal
-        view
-        returns (uint256 amount0, uint256 amount1)
-    {
-        (uint160 sqrtPriceX96,,,) = poolManager.getSlot0(cp.key.toId());
-        (amount0, amount1) = SwapAndAddMath.getAmountsForLiquidity(sqrtPriceX96, sqrtLower, sqrtUpper, liquidity);
-    }
-
     // ───────────────────────────────────────────── POSM / pool actions ─────────────────────────────────────────────
 
     /// @dev Deploys liquidity via POSM (MINT for new position, INCREASE for existing).

src/interfaces/ISwapAndAdd.sol

@@ -3,6 +3,7 @@ pragma solidity ^0.8.24;
 
 import {Currency} from "@uniswap/v4-core/src/types/Currency.sol";
 import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
+import {IHooks} from "@uniswap/v4-core/src/interfaces/IHooks.sol";
 
 import {IMulticall_v4} from "./IMulticall_v4.sol";
 
@@ -34,7 +35,7 @@ import {IMulticall_v4} from "./IMulticall_v4.sol";
 ///        (new NFT, cash-out, swept dust) is forced to the position owner to prevent value redirection.
 ///      - Unsupported Pools: Pools with hooks returning deltas (`BEFORE_SWAP_RETURNS_DELTA`, `AFTER_SWAP_RETURNS_DELTA`,
 ///        `AFTER_REMOVE_LIQUIDITY_RETURNS_DELTA`, `AFTER_ADD_LIQUIDITY_RETURNS_DELTA`) break settlement conservation
-///        and are unsupported. Failures revert atomically; funds remain safe. Dynamic fee, gating, and oracle hooks are supported.
+///        and are rejected upfront with `UnsupportedHookPermissions`. Dynamic fee, gating, and oracle hooks are supported.
 ///      - Known Limits: Fee-on-transfer and rebasing tokens are unsupported (atomic reverts or larger trim, never token loss).
 ///        Budgets within the pool's ~1-wei mint/burn rounding toll cannot settle and revert `InsufficientLiquidity`.
 ///      - HookData Reuse: The same `hookData` payload is passed to all hook callbacks in the operation; single-use
@@ -116,6 +117,9 @@ interface ISwapAndAdd is IMulticall_v4 {
     /// @notice Thrown when a `routeFunding` token is one of the pool currencies (use `amount0In`/`amount1In` instead).
     error InvalidFundingToken(Currency token);
 
+    /// @notice Thrown when the pool's hook carries a returns-delta permission (see the Unsupported Pools note).
+    error UnsupportedHookPermissions(IHooks hooks);
+
     /// @notice Represents a non-pool token amount pulled to fund an off-chain route.
     /// @param token The non-pool token address (or address(0) for native ETH).
     /// @param amount The amount to pull from caller via Permit2 (or expected msg.value for native ETH). A zero amount pulls nothing but sweeps unlisted donations of that token.
@@ -130,24 +134,24 @@ interface ISwapAndAdd is IMulticall_v4 {
     /// @param tickUpper Upper tick of the position range.
     /// @param amount0In Amount of token0 budget to pull from caller (can be 0).
     /// @param amount1In Amount of token1 budget to pull from caller (can be 0).
-    /// @param route Encoded Universal Router commands and inputs (empty for pure same-pool zap). Must scope input amounts explicitly (never spend entire contract balance).
-    /// @param routeFunding Optional non-pool tokens pulled to fund the route. Unused amounts are swept to `recipient`.
     /// @param minLiquidity Minimum liquidity required for the minted position (slippage floor).
     /// @param recipient Address that receives the minted position NFT and leftover dust.
-    /// @param hookData Arbitrary data passed to pool hooks (reused across all callbacks).
     /// @param deadline Timestamp after which the transaction will revert.
+    /// @param route Encoded Universal Router commands and inputs (empty for pure same-pool zap). Must scope input amounts explicitly (never spend entire contract balance).
+    /// @param routeFunding Optional non-pool tokens pulled to fund the route. Unused amounts are swept to `recipient`.
+    /// @param hookData Arbitrary data passed to pool hooks (reused across all callbacks).
     struct AddParams {
         PoolKey poolKey;
         int24 tickLower;
         int24 tickUpper;
         uint256 amount0In;
         uint256 amount1In;
-        bytes route;
-        TokenAmount[] routeFunding;
         uint256 minLiquidity;
         address recipient;
-        bytes hookData;
         uint256 deadline;
+        bytes route;
+        TokenAmount[] routeFunding;
+        bytes hookData;
     }
 
     /// @notice Create a new v4 position from a one- or two-sided token budget in a single transaction.
@@ -165,22 +169,22 @@ interface ISwapAndAdd is IMulticall_v4 {
     /// @param tokenId Existing position ID to increase.
     /// @param amount0In Amount of token0 budget to pull from caller (can be 0). Accrued fees are collected and reinvested automatically.
     /// @param amount1In Amount of token1 budget to pull from caller (can be 0). Accrued fees are collected and reinvested automatically.
-    /// @param route Encoded Universal Router commands and inputs (can be empty).
-    /// @param routeFunding Optional non-pool tokens pulled to fund the route. Unused amounts are swept to `recipient`.
     /// @param minLiquidityAdded Minimum liquidity that must be added to the position (slippage floor).
     /// @param recipient Destination for swept dust. Forced to position owner if caller is an operator.
-    /// @param hookData Arbitrary data passed to pool hooks.
     /// @param deadline Timestamp after which the transaction will revert.
+    /// @param route Encoded Universal Router commands and inputs (can be empty).
+    /// @param routeFunding Optional non-pool tokens pulled to fund the route. Unused amounts are swept to `recipient`.
+    /// @param hookData Arbitrary data passed to pool hooks.
     struct IncreaseParams {
         uint256 tokenId;
         uint256 amount0In;
         uint256 amount1In;
-        bytes route;
-        TokenAmount[] routeFunding;
         uint256 minLiquidityAdded;
         address recipient;
-        bytes hookData;
         uint256 deadline;
+        bytes route;
+        TokenAmount[] routeFunding;
+        bytes hookData;
     }
 
     /// @notice Top up an existing position with a one- or two-sided budget and reinvest accrued fees in a single transaction.
@@ -200,24 +204,24 @@ interface ISwapAndAdd is IMulticall_v4 {
     /// @param additional1 Signed delta for token1 with the same signed delta semantics.
     /// @param newTickLower Lower tick of the new position range.
     /// @param newTickUpper Upper tick of the new position range.
-    /// @param route Encoded Universal Router commands and inputs (can be empty).
-    /// @param routeFunding Optional non-pool tokens pulled to fund the route. Unused amounts are swept to `recipient`.
     /// @param minLiquidity Minimum liquidity required for the newly minted position (slippage floor).
     /// @param recipient Destination for the new position NFT, returned cash-out tokens, and dust. Forced to owner if caller is an operator.
-    /// @param hookData Arbitrary data passed to pool hooks.
     /// @param deadline Timestamp after which the transaction will revert.
+    /// @param route Encoded Universal Router commands and inputs (can be empty).
+    /// @param routeFunding Optional non-pool tokens pulled to fund the route. Unused amounts are swept to `recipient`.
+    /// @param hookData Arbitrary data passed to pool hooks.
     struct RebalanceParams {
         uint256 tokenId;
         int128 additional0;
         int128 additional1;
         int24 newTickLower;
         int24 newTickUpper;
-        bytes route;
-        TokenAmount[] routeFunding;
         uint256 minLiquidity;
         address recipient;
-        bytes hookData;
         uint256 deadline;
+        bytes route;
+        TokenAmount[] routeFunding;
+        bytes hookData;
     }
 
     /// @notice Withdraw an existing position entirely and redeploy it into a new tick range, optionally adding or cashing out tokens.
@@ -234,18 +238,18 @@ interface ISwapAndAdd is IMulticall_v4 {
 
     /// @notice Parameters for `compound`.
     /// @param tokenId Existing position ID whose accrued fees will be collected and reinvested.
-    /// @param route Encoded Universal Router commands and inputs (can be empty).
     /// @param minLiquidityAdded Minimum liquidity that must be added from reinvested fees (slippage floor).
     /// @param recipient Destination for swept dust. Forced to position owner if caller is an operator.
-    /// @param hookData Arbitrary data passed to pool hooks.
     /// @param deadline Timestamp after which the transaction will revert.
+    /// @param route Encoded Universal Router commands and inputs (can be empty).
+    /// @param hookData Arbitrary data passed to pool hooks.
     struct CompoundParams {
         uint256 tokenId;
-        bytes route;
         uint256 minLiquidityAdded;
         address recipient;
-        bytes hookData;
         uint256 deadline;
+        bytes route;
+        bytes hookData;
     }
 
     /// @notice Collect accrued fees on a position and reinvest them back into the same position in a single transaction.

src/libraries/SwapAndAddMath.sol

@@ -126,32 +126,42 @@ library SwapAndAddMath {
     }
 
     /// @notice Computes the liquidity to burn so that v4's rounded-DOWN return covers `amountToCover` of the
-    ///         deficit token.
+    ///         deficit token, capped at `maxLiquidity`.
     /// @dev Exact ceil inverse over `amountToCover + 1`: the nested-floor bound guarantees freed >= amountToCover.
     ///      Assumes the price is not past the range's far side for the deficit token (SwapAndAdd's reconcile
     ///      flow guarantees this); a price outside the near side clamps to the boundary.
-    /// @return liquidityToFree The round-up liquidity to burn, uncapped — callers cap against the liquidity they added.
+    /// @param maxLiquidity Cap on the result. A binding cap means burning even that much cannot cover the
+    ///        debt; the caller's settlement surfaces the shortfall.
+    /// @return liquidityToFree The round-up liquidity to burn, capped at `maxLiquidity`.
     function getLiquidityToFree(
         uint160 sqrtPriceX96,
         uint160 sqrtPriceLowerX96,
         uint160 sqrtPriceUpperX96,
         bool deficitIsCurrency1,
-        uint256 amountToCover
-    ) internal pure returns (uint256 liquidityToFree) {
+        uint256 amountToCover,
+        uint128 maxLiquidity
+    ) internal pure returns (uint128 liquidityToFree) {
+        // Forward check with v4's own round-DOWN burn formula: when even burning `maxLiquidity` cannot cover
+        // the debt, the cap binds and the inverse is skipped. This also bounds the inverse's inputs so its
+        // mulDiv result provably fits uint256 (its result exceeds the cap exactly when the check trips).
+        uint256 uncapped;
         if (deficitIsCurrency1) {
             // Token1 occupies [sqrtLower, min(price, sqrtUpper)]: amount1 = L * (hi - lo) / Q96.
             uint160 clampedUpper = sqrtPriceX96 < sqrtPriceUpperX96 ? sqrtPriceX96 : sqrtPriceUpperX96;
-            liquidityToFree =
-                FullMath.mulDivRoundingUp(amountToCover + 1, FixedPoint96.Q96, clampedUpper - sqrtPriceLowerX96);
+            if (amountToCover >= SqrtPriceMath.getAmount1Delta(sqrtPriceLowerX96, clampedUpper, maxLiquidity, false)) {
+                return maxLiquidity;
+            }
+            uncapped = FullMath.mulDivRoundingUp(amountToCover + 1, FixedPoint96.Q96, clampedUpper - sqrtPriceLowerX96);
         } else {
             // Token0 occupies [max(price, sqrtLower), sqrtUpper]: amount0 = L * Q96 * (hi - lo) / (hi * lo).
             uint160 clampedLower = sqrtPriceX96 > sqrtPriceLowerX96 ? sqrtPriceX96 : sqrtPriceLowerX96;
+            if (amountToCover >= SqrtPriceMath.getAmount0Delta(clampedLower, sqrtPriceUpperX96, maxLiquidity, false)) {
+                return maxLiquidity;
+            }
             uint256 intermediate = FullMath.mulDivRoundingUp(clampedLower, sqrtPriceUpperX96, FixedPoint96.Q96);
-            // Informational: At extreme prices where post-swap price is within sqrt-units of sqrtUpper with large
-            // deficit remaining, this intermediate quotient can overflow uint256 and revert (self-inflicted, safe).
-            liquidityToFree =
-                FullMath.mulDivRoundingUp(amountToCover + 1, intermediate, sqrtPriceUpperX96 - clampedLower);
+            uncapped = FullMath.mulDivRoundingUp(amountToCover + 1, intermediate, sqrtPriceUpperX96 - clampedLower);
         }
+        liquidityToFree = uncapped >= maxLiquidity ? maxLiquidity : uint128(uncapped);
     }
 
     /// @dev Values a token pair in the cheaper-token numeraire, weighting each side by its pips factor.

test/SwapAndAdd.t.sol

@@ -597,6 +597,30 @@ contract SwapAndAddTest is PosmTestSetup {
         zap.add(p);
     }
 
+    /// @dev Returns-delta hooks break settlement conservation and are rejected upfront with a typed error —
+    ///      the boundary is enforced in code, not just documented. One case per permission flag, each paired
+    ///      with the base flag v4 requires alongside it.
+    function test_add_returnsDeltaHook_revertsUnsupported() public {
+        uint160[4] memory flagged = [
+            Hooks.BEFORE_SWAP_FLAG | Hooks.BEFORE_SWAP_RETURNS_DELTA_FLAG,
+            Hooks.AFTER_SWAP_FLAG | Hooks.AFTER_SWAP_RETURNS_DELTA_FLAG,
+            Hooks.AFTER_ADD_LIQUIDITY_FLAG | Hooks.AFTER_ADD_LIQUIDITY_RETURNS_DELTA_FLAG,
+            Hooks.AFTER_REMOVE_LIQUIDITY_FLAG | Hooks.AFTER_REMOVE_LIQUIDITY_RETURNS_DELTA_FLAG
+        ];
+        ISwapAndAdd.AddParams memory p = _addParams(1e18, 1e18);
+        for (uint256 i = 0; i < flagged.length; i++) {
+            p.poolKey.hooks = IHooks(address(flagged[i]));
+            vm.expectRevert(abi.encodeWithSelector(ISwapAndAdd.UnsupportedHookPermissions.selector, p.poolKey.hooks));
+            zap.add(p);
+        }
+
+        // Negative control: a hook WITHOUT returns-delta permissions passes the gate — the same call
+        // proceeds into the flow and fails deeper on the (uninitialized) pool instead.
+        p.poolKey.hooks = IHooks(address(uint160(Hooks.BEFORE_SWAP_FLAG)));
+        vm.expectRevert(IPoolManager.PoolNotInitialized.selector);
+        zap.add(p);
+    }
+
     function test_rebalance_revertsIfNotAuthorized() public {
         (uint256 tokenId,,,) = zap.add(_addParams(0, 10e18));
         // do NOT approve the zap; call from a stranger