feat: introduce satisfies* API and complete internal modernization

BREAKING CHANGES:
- oneOf() method removed from ArrayValidator and ObjectValidator (now available only on primitive validators via OneOfTrait)

Added:
- New satisfies* API for enhanced logical combinators:
  - satisfiesAny(array , ?string  = null)
  - satisfiesAll(array , ?string  = null)
  - satisfiesNone(array , ?string  = null)
- Enhanced satisfies() method now accepts callable|FieldValidator instances
- OneOfTrait for type-safe oneOf() implementation on primitive validators
- Optional error message parameter for required() method

Changed:
- Deprecated instance methods anyOf(), allOf(), not() (maintained as aliases)
- Complete internal migration from addValidation() to satisfies():
  - StringValidator: 10 methods migrated
  - NumericConstraintsTrait: 5 methods migrated
  - Static combinators: Validator::anyOf(), allOf(), not() use new satisfies* API
- oneOf() now implemented as transformation, respecting execution order
- Updated test suite to use new satisfies* API (135 tests, 390 assertions)

Documentation:
- Updated all documentation to reflect new API
- Added comprehensive satisfies* API documentation
- Updated examples and guides
- Added deprecation notices for backward compatibility

This achieves complete internal API consistency while maintaining perfect backward compatibility.

Author: lemmon

AGENTS.md

@@ -23,15 +23,15 @@ A comprehensive, fluent validation library for PHP inspired by Valibot and Zod.
 
 ### Validation Capabilities
 - **Static Logical Combinators** - `Validator::allOf()`, `Validator::anyOf()`, `Validator::not()` for complex rule composition and mixed-type validation
-- **Instance Logical Combinators** - `allOf()`, `anyOf()`, `not()` instance methods for chaining validation rules
+- **New `satisfies*` API** - Enhanced instance logical combinators (`satisfiesAny()`, `satisfiesAll()`, `satisfiesNone()`) with support for mixed validators/callables
 - **Form-Safe Coercion** - Empty strings convert to `null` (not dangerous `0`/`0.0`/`false`) for primitives, empty structures for objects/arrays
 - **Array Filtering** - `filterEmpty()` method removes empty values while maintaining indexed array structure
 - **Type-Aware Transformations** - Revolutionary `transform()` and `pipe()` system with intelligent type context switching
-- **Custom Validation** - `satisfies()` method for business logic integration with optional error messages
+- **Custom Validation** - Enhanced `satisfies()` method accepting `FieldValidator` instances or callables with optional error messages (all internal validators migrated from deprecated `addValidation()`)
 - **Context-Aware Validation** - Custom validators receive `(value, key, input)` parameters
 - **Comprehensive Error Collection** - All validation errors collected, not just the first failure
 - **Smart Type Coercion** - Configurable automatic type conversion with form-friendly defaults
-- **Fluent API** - Chainable method calls for readable validation code
+- **Fluent API with guaranteed execution order** - Chainable method calls that execute in the exact order written
 
 ### Developer Experience
 - **Dual Validation Methods** - `validate()` (exception-based) and `tryValidate()` (tuple-based)
@@ -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, 131 tests, 375 assertions)
+- **Testing** - Pest PHP with organized test suite (10 focused test files, 135 tests, 390 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
@@ -108,9 +108,9 @@ tests/
 
 ### Key Metrics
 - **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
+- **35+ built-in validation methods** including static logical combinators, array filtering, type-aware transformations, form-safe coercion, and intuitive custom validation (all using modern `satisfies()` API internally)
 - **5,000+ lines of documentation** with practical examples and comprehensive coverage
-- **131 unit tests** with comprehensive coverage (375 assertions)
+- **135 unit tests** with comprehensive coverage (390 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

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 ## [Unreleased]
 
 ### Added
+- **New `satisfies*` API**: Enhanced instance logical combinators for improved API consistency and flexibility
+  - `satisfiesAny(array $validations, ?string $message = null)` - Validates that value passes ANY of the provided validators or callables
+  - `satisfiesAll(array $validations, ?string $message = null)` - Validates that value passes ALL of the provided validators or callables
+  - `satisfiesNone(array $validations, ?string $message = null)` - Validates that value satisfies NONE of the provided validators or callables
+  - **Enhanced `satisfies()` Method**: Now accepts `callable|FieldValidator` instances for maximum flexibility
+  - **Backward Compatibility**: Deprecated `anyOf()`, `allOf()`, `not()` instance methods maintained as aliases
+  - **API Clarity**: Eliminates confusion between static `Validator::anyOf()` and instance `$validator->anyOf()` methods
+  - Updated test metrics: 135 tests, 390 assertions
+- **Refactored `oneOf()` to `OneOfTrait`**: Improved type safety and execution order consistency
+  - **Type Safety**: `oneOf()` now only available on primitive validators (`StringValidator`, `IntValidator`, `FloatValidator`, `BoolValidator`)
+  - **Execution Order**: `oneOf()` now implemented as transformation, respecting fluent API chain position
+  - **Logical Consistency**: Removed from complex types (`ArrayValidator`, `ObjectValidator`) where it doesn't make semantic sense
+  - **Breaking Change**: `ArrayValidator` and `ObjectValidator` no longer have `oneOf()` method
+  - Added comprehensive test coverage and removed invalid test cases
 - **Form-Safe Empty String Coercion**: Enhanced ObjectValidator and AssociativeValidator coercion for better form handling
   - `ObjectValidator::coerce()`: Empty strings (`''`) now coerce to empty `stdClass` objects
   - `AssociativeValidator::coerce()`: Empty strings (`''`) now coerce to empty arrays `[]`
@@ -16,6 +30,13 @@ All notable changes to this project will be documented in this file.
   - **API Consistency**: All validation methods now support optional custom error messages
   - **Better UX**: Context-specific error messages for different forms and use cases
   - Maintains backward compatibility with existing code
+- **Internal API Modernization**: Complete migration from deprecated `addValidation()` to `satisfies()` throughout codebase
+  - **StringValidator**: All 10 validation methods (`email()`, `url()`, `uuid()`, `ip()`, `minLength()`, `maxLength()`, `length()`, `pattern()`, `datetime()`, `date()`) now use `satisfies()` internally
+  - **NumericConstraintsTrait**: All 5 constraint methods (`min()`, `max()`, `multipleOf()`, `positive()`, `negative()`) now use `satisfies()` internally
+  - **Static Methods**: `Validator::anyOf()`, `Validator::allOf()`, `Validator::not()` now use new `satisfies*` API internally
+  - **Future-Proofing**: All internal code ready for `addValidation()` removal in v1.0.0
+  - **Consistency**: Single source of truth for custom validation logic across entire codebase
+  - Maintains perfect backward compatibility for users still using deprecated methods
 
 ### Fixed
 - **CRITICAL BUG**: Fixed execution order for `required()` and `nullifyEmpty()` methods to respect fluent API contract

IDEAS.md

@@ -48,7 +48,7 @@ $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 (131 tests, 375 assertions)
+- ✅ Comprehensive test coverage (135 tests, 390 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
@@ -58,6 +58,8 @@ $formatted = Validator::isString()
 - ✅ 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
 - ✅ Fixed execution order for required() and nullifyEmpty() methods to respect fluent API contract
+- ✅ New `satisfies*` API for enhanced instance logical combinators with improved consistency
+- ✅ Refactored `oneOf()` to `OneOfTrait` for better type safety and execution order
 
 ### Intuitive Custom Validation (v0.6.0)
 **Status**: ✅ **IMPLEMENTED**
@@ -303,7 +305,7 @@ $validator = Validator::conditional(
 **Concept**: Cache validation results for expensive operations.
 ```php
 $validator = Validator::isString()
-    ->addValidation($expensiveValidation)
+    ->satisfies($expensiveValidation)
     ->withCache($cacheAdapter, ttl: 3600);
 ```
 **Benefits**:

README.md

@@ -26,15 +26,15 @@ Rather than reimplementing every possible transformation or validation rule, Lem
 **Key Design Principles:**
 
 - **Form Safety First**: Empty strings coerce to `null` (not dangerous `0`/`false`) to prevent real-world issues like accidental zero bank balances
-- **Fluent API**: Validation rules read like natural language and execute in the order written - `Validator::isString()->pipe('trim')->nullifyEmpty()->required()`
+- **Fluent API with Execution Order Guarantee**: Validation rules read like natural language and execute in the exact order written - `Validator::isString()->pipe('trim')->nullifyEmpty()->required()`
 - **Comprehensive Error Collection**: All validation errors are collected, not just the first failure
 - **Type-Aware Transformations**: Intelligent transformation system that maintains type context and handles coercion automatically
 - **Extensible Architecture**: Generic transformation methods work with any PHP callable or external library
 
 ## Features
 
 - **Type-safe validation** for strings, integers, floats, arrays, and objects
-- **Fluent, chainable API** for readable and maintainable validation rules
+- **Fluent, chainable API** with guaranteed execution order for readable and maintainable validation rules
 - **Comprehensive error collection** with detailed, structured feedback
 - **Intuitive custom validation** with `satisfies()` method and optional error messages
 - **Logical combinators** (`Validator::allOf()`, `Validator::anyOf()`, `Validator::not()`) for complex validation logic

ROADMAP.md

@@ -50,6 +50,11 @@ This roadmap outlines the strategic development plan for future releases, priori
   - Updated Core Concepts, Basic Usage, and API Reference guides
   - Updated Error Handling, Numeric, String, and Object Validation guides
   - Maintained backward compatibility with deprecated `addValidation()` method
+- [x] ✅ **Complete internal API modernization** - Migrate all internal code from `addValidation()` to `satisfies()`
+  - Migrated all StringValidator methods (10 methods) to use `satisfies()` internally
+  - Migrated all NumericConstraintsTrait methods (5 methods) to use `satisfies()` internally
+  - Updated static logical combinators to use new `satisfies*` API internally
+  - Codebase now fully consistent with modern API while maintaining backward compatibility
 
 ### Critical Bug Fixes
 - [x] ✅ **Fix ObjectValidator null property handling** - `isset($validatedFieldValue)` excluded null properties from result object
@@ -152,10 +157,10 @@ use Ramsey\Uuid\Uuid;
 use Hidehalo\Nanoid\Client as NanoidClient;
 
 $uuidValidator = Validator::isString()
-    ->addValidation(fn($v) => Uuid::isValid($v), 'Must be valid UUID');
+    ->satisfies(fn($v) => Uuid::isValid($v), 'Must be valid UUID');
 
 $nanoidValidator = Validator::isString()
-    ->addValidation(fn($v) => (new NanoidClient())->isValid($v), 'Must be valid Nano ID');
+    ->satisfies(fn($v) => (new NanoidClient())->isValid($v), 'Must be valid Nano ID');
 
 // Real-world form data normalization (with dedicated methods):
 $formValidator = Validator::isAssociative([
@@ -304,7 +309,7 @@ $stringValidator = Validator::isString()
 - [ ] **Interactive documentation** - Runnable examples
 
 ### Testing & Quality
-- [x] ✅ Organized test suite (10 focused test files, 127 tests, 363 assertions)
+- [x] ✅ Organized test suite (10 focused test files, 135 tests, 390 assertions)
 - [x] ✅ 100% PHPStan compliance
 - [x] ✅ PHP-CS-Fixer standards
 - [x] ✅ Static logical combinators test coverage

docs/api-reference/validator-factory.md

@@ -629,6 +629,126 @@ $validator = Validator::isString()
 $result = $validator->validate(''); // Returns: 'N/A'
 ```
 
+---
+
+### `oneOf(array $values, ?string $message = null): self`
+
+**Available on:** `StringValidator`, `IntValidator`, `FloatValidator`, `BoolValidator` only
+
+Restricts the value to one of the specified allowed values. This method is implemented as a transformation and respects the fluent API execution order.
+
+```php
+// String with allowed values
+$status = Validator::isString()
+    ->oneOf(['active', 'inactive', 'pending'], 'Invalid status')
+    ->validate('active'); // ✅ Valid
+
+// Integer with allowed values
+$priority = Validator::isInt()
+    ->oneOf([1, 2, 3, 4, 5], 'Priority must be 1-5')
+    ->validate(3); // ✅ Valid
+
+// Execution order matters
+$validator = Validator::isString()
+    ->pipe('trim', 'strtolower')  // Transform first
+    ->oneOf(['yes', 'no'])        // Then validate allowed values
+    ->validate('  YES  '); // ✅ Valid (becomes 'yes' after transformation)
+```
+
+**Parameters:**
+- `$values`: Array of allowed values (compared using strict equality)
+- `$message` (optional): Custom error message for invalid values
+
+**Note:** This method is not available on `ArrayValidator` or `ObjectValidator` as it doesn't make semantic sense for complex types.
+
+---
+
+## Instance Logical Combinators
+
+All validators support enhanced logical combinators for complex validation scenarios:
+
+### `satisfiesAny(array $validations, ?string $message = null): self`
+
+Validates that the value passes ANY of the provided validators or callables.
+
+```php
+// Mixed validation - accepts multiple validator types
+$flexibleValidator = Validator::isString()
+    ->satisfiesAny([
+        Validator::isString()->email(),
+        Validator::isString()->url(),
+        fn($v) => filter_var($v, FILTER_VALIDATE_IP) !== false
+    ], 'Must be email, URL, or IP address');
+
+$result1 = $flexibleValidator->validate('user@example.com'); // ✅ Valid (email)
+$result2 = $flexibleValidator->validate('https://example.com'); // ✅ Valid (URL)
+$result3 = $flexibleValidator->validate('192.168.1.1'); // ✅ Valid (IP)
+```
+
+---
+
+### `satisfiesAll(array $validations, ?string $message = null): self`
+
+Validates that the value passes ALL of the provided validators or callables.
+
+```php
+// Complex validation combining multiple rules
+$strongPassword = Validator::isString()
+    ->minLength(8)
+    ->satisfiesAll([
+        fn($v) => preg_match('/[A-Z]/', $v), // Has uppercase
+        fn($v) => preg_match('/[a-z]/', $v), // Has lowercase
+        fn($v) => preg_match('/[0-9]/', $v), // Has number
+        fn($v) => preg_match('/[!@#$%^&*]/', $v) // Has special char
+    ], 'Password must contain uppercase, lowercase, number, and special character');
+```
+
+---
+
+### `satisfiesNone(array $validations, ?string $message = null): self`
+
+Validates that the value satisfies NONE of the provided validators or callables.
+
+```php
+// Exclusion validation - value must not match any pattern
+$safeUsername = Validator::isString()
+    ->satisfiesNone([
+        fn($v) => in_array(strtolower($v), ['admin', 'root', 'user']),
+        fn($v) => preg_match('/^\d+$/', $v), // Not all numbers
+        Validator::isString()->email() // Not an email format
+    ], 'Username cannot be reserved word, all numbers, or email format');
+```
+
+---
+
+### `satisfies(callable|FieldValidator $validation, ?string $message = null): self`
+
+Enhanced custom validation accepting both callables and `FieldValidator` instances.
+
+```php
+// Using callable
+$positiveNumber = Validator::isInt()
+    ->satisfies(fn($v) => $v > 0, 'Must be positive');
+
+// Using FieldValidator instance
+$emailOrPhone = Validator::isString()
+    ->satisfies(
+        Validator::isString()->email(),
+        'Must be valid email format'
+    );
+
+// Context-aware validation
+$passwordConfirm = Validator::isString()
+    ->satisfies(
+        function ($value, $key, $input) {
+            return isset($input['password']) && $value === $input['password'];
+        },
+        'Password confirmation must match'
+    );
+```
+
+**Note:** The old `anyOf()`, `allOf()`, and `not()` instance methods are deprecated but maintained for backward compatibility.
+
 ## See Also
 
 - [String Validation Guide](../guides/string-validation.md) - String-specific methods and examples

docs/getting-started/core-concepts.md

@@ -45,15 +45,17 @@ All validators extend `FieldValidator`, which provides:
 - `required(): static` - Makes the field mandatory
 - `default(mixed $value): static` - Sets default value for null inputs
 - `coerce(): static` - Enables automatic type conversion
-- `oneOf(array $values): static` - Restricts to specific values
+- `oneOf(array $values): static` - Restricts to specific values (primitive validators only)
 
 ### Custom Validation
-- `satisfies(callable $rule, ?string $message = null): static` - Adds custom rules with optional error message
+- `satisfies(callable|FieldValidator $rule, ?string $message = null): static` - Enhanced custom validation accepting validators or callables
 
-### Logical Combinators
-- `allOf(array $validators): static` - Must pass all validators (instance method)
-- `anyOf(array $validators): static` - Must pass at least one validator (instance method)
-- `not(FieldValidator $validator): static` - Must NOT pass the validator (instance method)
+### Instance Logical Combinators
+- `satisfiesAll(array $validations): static` - Must pass all validators/callables (replaces `allOf()`)
+- `satisfiesAny(array $validations): static` - Must pass at least one validator/callable (replaces `anyOf()`)
+- `satisfiesNone(array $validations): static` - Must NOT pass any validator/callable (replaces `not()`)
+
+**Note:** The old `allOf()`, `anyOf()`, and `not()` instance methods are deprecated but maintained for backward compatibility.
 
 ### Static Logical Combinators
 - `Validator::allOf(array $validators)` - Creates validator that must pass all validators

docs/guides/array-validation.md

@@ -233,10 +233,15 @@ $validator->validate(null); // Throws ValidationException
 ### Array Length Constraints
 
 ```php
-// Using oneOf for specific arrays
-$validator = Validator::isArray()->oneOf([[1, 2], [3, 4]]);
+// For specific array validation, use custom validation
+$validator = Validator::isArray()->satisfies(
+    fn($value) => in_array($value, [[1, 2], [3, 4]], true),
+    'Array must be exactly [1, 2] or [3, 4]'
+);
 $result = $validator->validate([1, 2]); // Valid
 $validator->validate([1, 2, 3]); // Throws ValidationException
+
+// Note: oneOf() is not available on ArrayValidator as it doesn't make semantic sense for complex types
 ```
 
 ### Empty Array Handling

src/Lemmon/BoolValidator.php

@@ -4,6 +4,7 @@
 
 class BoolValidator extends FieldValidator
 {
+    use OneOfTrait;
     /**
      * @inheritDoc
      */