fix: resolve floating-point precision bug in multipleOf validation

- Issue: Validator::isFloat()->multipleOf(0.01)->validate(500.01) failed due to precision
- Root cause: fmod(500.01, 0.01) returned 0.009999999999980497 instead of 0.0
- Solution: Implement epsilon comparison (1e-9 tolerance) for floating-point remainders
- Impact: Decimal multiples (currency, measurements) now validate correctly

Technical details:
- Enhanced multipleOf() with dual condition: abs(remainder) < epsilon || abs(remainder - divisor) < epsilon
- Maintains integer path performance (no epsilon needed for exact arithmetic)
- Handles both near-zero and near-divisor remainder cases

Examples now working:
- 500.01 multipleOf 0.01 ✅
- 19.99 multipleOf 0.01 ✅
- 1234.56 multipleOf 0.01 ✅

- Add comprehensive test coverage for floating-point precision edge cases
- Update project documentation with bug fix details
- Total test suite: 127 tests, 363 assertions

Author: lemmon

AGENTS.md

@@ -65,7 +65,7 @@ A comprehensive, fluent validation library for PHP inspired by Valibot and Zod.
 ## 🔧 Development Workflow
 
 ### Code Quality
-- **Testing** - Pest PHP with organized test suite (10 focused test files, 126 tests, 358 assertions)
+- **Testing** - Pest PHP with organized test suite (10 focused test files, 127 tests, 363 assertions)
 - **Static Analysis** - PHPStan at maximum level for type safety
 - **Code Style** - PHP-CS-Fixer for consistent formatting
 - **Performance** - Optimized validation logic with eliminated code duplication
@@ -110,7 +110,7 @@ tests/
 - **8 validator types** covering all PHP data types
 - **35+ built-in validation methods** including static logical combinators, array filtering, type-aware transformations, form-safe coercion, and intuitive custom validation
 - **5,000+ lines of documentation** with practical examples and comprehensive coverage
-- **126 unit tests** with comprehensive coverage (358 assertions)
+- **127 unit tests** with comprehensive coverage (363 assertions)
 - **Zero technical debt** with modern PHP 8.1+ codebase
 - **Zero dead links** in documentation with seamless navigation
 - **Complete API documentation** with accurate method signatures and examples

CHANGELOG.md

@@ -13,6 +13,12 @@ All notable changes to this project will be documented in this file.
   - Added comprehensive test coverage (6 new tests, 23 new assertions)
 
 ### Fixed
+- **CRITICAL BUG**: Fixed floating-point precision issue in `multipleOf()` validation
+  - **Issue**: `Validator::isFloat()->multipleOf(0.01)->validate(500.01)` failed due to floating-point arithmetic precision
+  - **Root Cause**: `fmod(500.01, 0.01)` returned `0.009999999999980497` instead of `0.0`
+  - **Fix**: Implemented epsilon comparison (`1e-9` tolerance) for floating-point remainder validation
+  - **Impact**: Decimal multiples (currency, measurements) now validate correctly
+  - Added comprehensive test coverage for floating-point precision edge cases
 - **CRITICAL BUG**: Fixed schema validation field inclusion behavior in ObjectValidator and AssociativeValidator
   - **Issue**: Validators were incorrectly including ALL schema fields in results, even when not provided in input
   - **Fix**: Now only includes fields that were actually provided in input OR have default values applied

IDEAS.md

@@ -48,14 +48,15 @@ $formatted = Validator::isString()
 - ✅ Smart array coercion (indexed arrays auto-reindex, associative keys preserved)
 - ✅ Clean variadic syntax with `pipe(...$transformers)`
 - ✅ Perfect integration with external libraries (Laravel, Symfony)
-- ✅ Comprehensive test coverage (126 tests, 358 assertions)
+- ✅ Comprehensive test coverage (127 tests, 363 assertions)
 - ✅ Complete documentation overhaul with comprehensive coverage across all guides
 - ✅ Fixed all dead links in documentation for seamless navigation
 - ✅ Added type-aware transformation system documentation with detailed examples
 - ✅ Documented `filterEmpty()` method with practical use cases
 - ✅ Updated API reference to match actual implementation
 - ✅ Fixed critical schema validation bug - only include provided fields or fields with defaults in results
 - ✅ Enhanced form-safe coercion - empty strings coerce to empty objects/arrays for better form handling
+- ✅ Fixed floating-point precision bug in multipleOf validation for accurate decimal calculations
 
 ### Intuitive Custom Validation (v0.6.0)
 **Status**: ✅ **IMPLEMENTED**

ROADMAP.md

@@ -304,11 +304,12 @@ $stringValidator = Validator::isString()
 - [ ] **Interactive documentation** - Runnable examples
 
 ### Testing & Quality
-- [x] ✅ Organized test suite (10 focused test files, 120 tests, 335 assertions)
+- [x] ✅ Organized test suite (10 focused test files, 127 tests, 363 assertions)
 - [x] ✅ 100% PHPStan compliance
 - [x] ✅ PHP-CS-Fixer standards
 - [x] ✅ Static logical combinators test coverage
 - [x] ✅ Comprehensive schema validation test coverage
+- [x] ✅ Floating-point precision bug fixes with comprehensive edge case testing
 - [ ] **Mutation testing** - Enhanced test quality verification
 - [ ] **Property-based testing** - Randomized validation testing
 - [ ] **Performance benchmarking** - Continuous performance monitoring

src/Lemmon/NumericConstraintsTrait.php

@@ -54,7 +54,11 @@ function ($value, $key = null, $input = null) use ($divisor) {
                 if (is_int($divisor) && is_int($value)) {
                     return $value % $divisor === 0;
                 }
-                return fmod((float) $value, (float) $divisor) === 0.0;
+
+                // Use epsilon comparison for floating-point precision
+                $remainder = fmod((float) $value, (float) $divisor);
+                $epsilon = 1e-9; // Tolerance for floating-point comparison
+                return abs($remainder) < $epsilon || abs($remainder - $divisor) < $epsilon;
             },
             $message ?? "Value must be a multiple of {$divisor}"
         );

tests/FloatValidatorTest.php

@@ -60,3 +60,17 @@
 
     $positiveValidator->validate(-1);
 })->throws(Lemmon\ValidationException::class, 'Value must be positive');
+
+it('should handle floating-point precision in multipleOf validation', function () {
+    // Test cases that previously failed due to floating-point precision
+    $validator = Validator::isFloat()->multipleOf(0.01);
+
+    expect($validator->validate(500.01))->toBe(500.01); // Original bug case
+    expect($validator->validate(19.99))->toBe(19.99);   // Another precision case
+    expect($validator->validate(1234.56))->toBe(1234.56); // Larger number
+
+    // Test with smaller precision
+    $smallValidator = Validator::isFloat()->multipleOf(0.001);
+    expect($smallValidator->validate(0.999))->toBe(0.999);
+    expect($smallValidator->validate(1.001))->toBe(1.001);
+});