fix(validator): isolate shared validator state across clones and schema reuse

- Clone schema field validators at construction time so shared instances do not leak mutations into schemas
- Make coerceAll() recursive through nested schemas and array item validators; each field is cloned so shared definitions are not mutated
- Clone FieldValidator operands in satisfies(), satisfiesAll(), satisfiesAny(), satisfiesNone(), and contains() at capture time; rebuild on __clone() to isolate pipeline state
- Reset transient currentType before and after each tryValidate() run so transform/pipe validators remain repeatable across calls and clones
- Track bindable flag per pipeline step so __clone() skips Closure::bindTo() on static closures (e.g. from in()), avoiding PHP warnings
- Add defaultUsing(callable) for fresh mutable defaults per validation run; default() returns objects by handle
- Simplify FloatValidator coercion (remove redundant ternary)

Author: lemmon

CHANGELOG.md

@@ -7,9 +7,16 @@ All notable changes to this project will be documented in this file.
 ### Fixed
 
 - `BoolValidator::coerce()` no longer string-casts non-scalar values (arrays triggered `E_WARNING`, objects without `__toString` threw `Error`); non-scalars are passed through to type validation, which raises `ValidationException` as for other invalid types
+- `coerceAll()` no longer calls `coerce()` on schema field validators in place (which leaked coercion to every other schema reusing the same `FieldValidator` instance); `coerceAll()` now replaces each field with a clone that has coercion enabled
+- `coerceAll()` is now recursive: nested `AssociativeValidator`, `ObjectValidator`, and `ArrayValidator` (with item validators) all propagate coercion to their children; previously only top-level schema fields were coerced
+- `FieldValidator::__clone()` skips `Closure::bindTo()` for static closures (for example from `in()`), avoiding PHP warnings when cloning such validators; pipeline steps now carry a `bindable` flag set at insertion time so cloning no longer needs `ReflectionFunction`
+- `satisfies()`, `satisfiesAll()`, `satisfiesAny()`, `satisfiesNone()`, and `ArrayValidator::contains()` now clone any `FieldValidator` operand at capture time and rebuild those operands when the outer validator is cloned, so later mutations or clone-local pipeline state do not leak across validator instances
+- `FieldValidator::tryValidate()` now resets transient type-tracking before and after every validation run, so validators that use `transform()`/`pipe()` remain repeatable across multiple calls and clones do not inherit stale runtime state
+- `default()` no longer deep-copies object values; object defaults are returned as-is (shared by handle). Use `defaultUsing()` when each validation run needs a fresh object instance
 
 ### Added
 
+- `defaultUsing(callable $factory)` on `FieldValidator`: invokes the factory whenever validation resolves to null, providing a fresh default per validation run; intended for mutable domain objects or other defaults that should not be shared across validations or clones
 - `passthrough()` on `AssociativeValidator` and `ObjectValidator`: copy undeclared keys or public properties from the input to the validated output without validating them; declared schema fields are still validated; values already written from the schema (including `outputKey` targets) are not overwritten by passthrough
 
 ## [0.14.0] - 2026-03-23

docs/api-reference/validator-factory.md

@@ -707,6 +707,8 @@ $strictString = Validator::isString(); // No coerce() call
 
 Sets a default value when validation passes but the value is null.
 
+Scalars and flat arrays (no nested objects) are safe because PHP copies them by value. Object defaults and arrays containing objects are returned as-is, sharing the same object handles across runs; use `defaultUsing()` when the default contains any mutable objects.
+
 ```php
 $validator = Validator::isString()
     ->nullifyEmpty() // Empty strings become null
@@ -717,6 +719,22 @@ $result = $validator->validate(''); // Returns: 'N/A'
 
 ---
 
+### `defaultUsing(callable $factory): self`
+
+Invokes the factory whenever validation resolves to null, so each validation run receives a fresh default value.
+
+```php
+$validator = Validator::isObject()->defaultUsing(
+    static fn() => (object) ['active' => true],
+);
+
+$result = $validator->validate(null); // Returns a new stdClass each time
+```
+
+Use this whenever the default contains mutable objects -- whether a plain object or an array with nested objects. Each call to `validate()` will invoke the factory and receive a fresh instance.
+
+---
+
 ### `outputKey(string $key): self`
 
 **Schema fields only.** Emits the validated value under a different key than the input field. Only applies when the validator is used inside `Validator::isAssociative()` or `Validator::isObject()`.

docs/getting-started/core-concepts.md

@@ -46,6 +46,7 @@ All validators extend `FieldValidator`, which provides:
 
 - `required(): static` - Makes the field mandatory
 - `default(mixed $value): static` - Sets default value for null inputs
+- `defaultUsing(callable $factory): static` - Builds a fresh default for each null input
 - `coerce(): static` - Enables automatic type conversion
 - `in(array $values): static` - Restricts to specific values (primitive validators only)
 

docs/guides/object-validation.md

@@ -283,7 +283,7 @@ $result = $schema->validate($input);
 $schema = Validator::isAssociative([
     'level' => Validator::isInt()->in([3, 5, 8]),
     'override' => Validator::isBool()
-])->coerceAll(); // Enables coercion for all fields
+])->coerceAll(); // Recursively enables coercion for all fields, nested schemas, and array items
 
 $input = [
     'level' => '5', // String coerced to int
@@ -294,6 +294,8 @@ $result = $schema->validate($input);
 // Result: ['level' => 5, 'override' => false]
 ```
 
+> **Scope:** `coerceAll()` propagates through schema fields, nested schemas, and array item validators. It does not reach into assertion operands -- validators passed to `satisfies()`, `satisfiesAll()`, `satisfiesAny()`, `satisfiesNone()`, or `contains()`. Call `coerce()` on those validators individually when needed.
+
 ### Object-Array Coercion
 
 ```php

llms.txt

@@ -11,6 +11,7 @@
     - `pipe(callable)`: Skips `null` values (type-preserving, expects specific type).
     - `transform(callable, bool $skipNull = true)`: Skips `null` by default (most type conversions don't need null). Set `$skipNull = false` to process null values.
 - **Pipeline Order:** Pipeline steps execute in the exact order defined. `default()` and `required()` are flags evaluated after the pipeline regardless of position: `default()` is the last-resort fallback for null, `required()` enforces presence after default has had its chance.
+- **Mutable Defaults:** `default()` stores the value as-is; scalars and flat arrays are copied by value in PHP, but objects (and arrays containing objects) share handles across runs. Use `defaultUsing()` when the default contains any mutable objects.
 - **Transformation Types:**
   - `pipe(callable)`: Intended for sanitization. Preserves type context and applies type-coercion to result.
   - `transform(callable)`: Intended for type conversion. Updates type context; no coercion.
@@ -54,6 +55,7 @@ _Available on all validators_
 ```php
 required(?string $message = null): static
 default(mixed $value): static
+defaultUsing(callable(): mixed $factory): static
 coerce(): static
 outputKey(string $key): static (schema fields only: output under different key, e.g. input service_id -> output service)
 nullifyEmpty(): static (transforms '' or [] to null)
@@ -147,7 +149,7 @@ _Schema validation_
 
 ```php
 // Constructor accepts array<string, FieldValidator>
-coerceAll(): static // Recursively enables coercion on schema fields
+coerceAll(): static // Recursively enables coercion on schema fields, nested schemas, and array item validators (each validator is cloned so shared instances are not mutated); does not propagate into assertion operands (satisfies, contains, etc.) -- call coerce() on those individually
 passthrough(): static // Copy undeclared keys/properties from input to output without validating them; schema fields still validated; does not overwrite keys already set from the schema (including outputKey targets)
 ```
 

src/Lemmon/Validator/ArrayValidator.php

@@ -8,6 +8,7 @@ class ArrayValidator extends FieldValidator
 {
     private ?FieldValidator $itemValidator = null;
     private bool $filterEmpty = false;
+    private bool $coerceAll = false;
 
     /**
      * @inheritDoc
@@ -25,7 +26,7 @@ protected function getValidatorType(): string
      */
     public function items(FieldValidator $validator): self
     {
-        $this->itemValidator = $validator;
+        $this->itemValidator = $this->coerceAll ? $validator->clone()->coerceAll() : $validator->clone();
         return $this;
     }
 
@@ -166,24 +167,47 @@ static function ($value, $key = null, $input = null) use ($fieldName, $message)
      */
     public function contains(mixed $valueOrValidator, ?string $message = null): static
     {
-        return $this->satisfies(
-            static function ($value, $key = null, $input = null) use ($valueOrValidator) {
-                if ($valueOrValidator instanceof FieldValidator) {
-                    // Check if any item matches the validator
-                    foreach ($value as $item) {
-                        [$valid] = $valueOrValidator->tryValidate($item);
-                        if ($valid) {
-                            return true;
-                        }
+        $message ??= 'Value must contain the required item';
+
+        if ($valueOrValidator instanceof FieldValidator) {
+            $valueOrValidator = $valueOrValidator->clone();
+
+            $this->addValidationStep(
+                self::buildContainsRule($valueOrValidator),
+                $message,
+                static fn(): \Closure => self::buildValidationOperation(
+                    self::buildContainsRule($valueOrValidator->clone()),
+                    $message,
+                ),
+            );
+
+            return $this;
+        }
+
+        $this->addValidationStep(
+            self::buildContainsRule($valueOrValidator),
+            $message,
+        );
+
+        return $this;
+    }
+
+    private static function buildContainsRule(mixed $valueOrValidator): \Closure
+    {
+        return static function ($value, $key = null, $input = null) use ($valueOrValidator): bool {
+            if ($valueOrValidator instanceof FieldValidator) {
+                foreach ($value as $item) {
+                    [$valid] = $valueOrValidator->tryValidate($item);
+                    if ($valid) {
+                        return true;
                     }
-                    return false;
                 }
 
-                // Check if array contains the specific value (strict comparison)
-                return in_array($valueOrValidator, $value, true);
-            },
-            $message ?? 'Value must contain the required item',
-        );
+                return false;
+            }
+
+            return in_array($valueOrValidator, $value, true);
+        };
     }
 
     /**
@@ -268,6 +292,19 @@ protected function validateType(mixed $value, string $key): mixed
         return $value;
     }
 
+    public function coerceAll(): static
+    {
+        if ($this->coerceAll) {
+            return $this;
+        }
+        $this->coerce = true;
+        $this->coerceAll = true;
+        if ($this->itemValidator !== null) {
+            $this->itemValidator = $this->itemValidator->coerceAll();
+        }
+        return $this;
+    }
+
     public function __clone()
     {
         parent::__clone();

src/Lemmon/Validator/AssociativeValidator.php

@@ -13,7 +13,11 @@ class AssociativeValidator extends FieldValidator
      */
     public function __construct(
         private array $schema,
-    ) {}
+    ) {
+        foreach ($this->schema as $key => $validator) {
+            $this->schema[$key] = $validator->clone();
+        }
+    }
 
     /**
      * @inheritDoc
@@ -55,10 +59,6 @@ protected function validateType(mixed $value, string $key): mixed
         $errors = [];
 
         foreach ($this->schema as $fieldKey => $validator) {
-            if ($this->coerceAll) {
-                $validator->coerce();
-            }
-
             // Get field value (null if not present)
             $fieldValue = array_key_exists($fieldKey, $value) ? $value[$fieldKey] : null;