feat(ArrayValidator): add uniqueField() for cross-item uniqueness validation

- Add uniqueField(string $fieldName, ?string $message = null) convenience method
- Produces field-level error paths (e.g., symlinks.2.destination) via nested error structure
- Skip items where field is null or missing; use serialize() for strict type comparison
- Fix json_encode false fallback for non-encodable values; remove dead-code satisfies fallback
- Add edge-case tests: empty array, 3+ duplicates, scalar items, filterEmpty combo
- Update ROADMAP with message placeholders idea

Author: lemmon

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- `uniqueField(string $fieldName, ?string $message = null)` on `ArrayValidator` for cross-item uniqueness validation of a nested field; convenience wrapper around `satisfies()` that produces field-level error paths (e.g., `symlinks.2.destination`) by structuring errors as `[index => [fieldName => [message]]]`; skips items where the field is null or missing; works with both associative arrays and objects; uses strict comparison via `serialize()` to distinguish types
+
 ## [0.13.0] - 2026-03-06
 
 ### Added

ROADMAP.md

@@ -16,7 +16,8 @@ Focused on core validation primitives, consistent pipelines, and extensibility v
 - [x] Universal allowed-value validators: `const()` (single allowed value), `enum()` (PHP BackedEnum)
 - [x] Schema output key remapping: `outputKey(string $key)`
 - [ ] Structured error codes in validation errors (backward compatible)
-- [ ] ArrayValidator `uniqueField(string $fieldName, ?string $message = null)`
+- [ ] Message placeholders for custom error messages (e.g., `{value}`, `{index}`) -- pair with error codes
+- [x] ArrayValidator `uniqueField(string $fieldName, ?string $message = null)`
 - [ ] Mutation testing pilot (Infection + baseline)
 - [ ] Property-based tests for core validators
 

TASKS.md

@@ -1,15 +1,31 @@
 # Task Pool (next steps)
 
-Public repo; keep this list short (about 7) and up to date. Rules: no numbering (keeps churn low), prune completed items, and replace them with the next priority. Contributors: pick one task, keep PRs focused, and update the list as things land.
+Public repo; keep this list short (about 7) and up to date. No numbering. Prune completed items and replace with the next priority. Contributors: pick one task, keep PRs focused, update the list as things land.
 
 - Structured error codes
-  - Add programmatic error codes to validation errors (e.g., 'STRING_TOO_SHORT', 'INVALID_EMAIL') for better error handling and i18n support; keep backward compatibility.
+
+  Add programmatic error codes to validation errors (e.g., STRING_TOO_SHORT, INVALID_EMAIL) for better error handling and i18n support; keep backward compatibility.
 
 - Mutation testing pilot
-  - Wire Infection (or similar) to the test suite, add baseline config, and document how to run it locally for enhanced test quality verification.
+
+  Wire Infection (or similar) to the test suite, add baseline config, and document how to run it locally for enhanced test quality verification.
 
 - Property-based tests
-  - Add a small property-based test set for key validators (string patterns, numeric constraints) to harden edge cases and catch regressions.
 
-- `uniqueField()` array validation method
-  - Add `uniqueField(string $fieldName, ?string $message = null)` to ArrayValidator for validating uniqueness of nested fields across array items; convenience wrapper around `satisfies()` that automatically handles nested error structure for field-level error paths (e.g., `symlinks.2.destination`); common use case that deserves convenience method similar to Laravel's `distinct` rule.
+  Add a small property-based test set for key validators (string patterns, numeric constraints) to harden edge cases and catch regressions.
+
+- Deprecation cleanup
+
+  Remove or finalize deprecated methods (addValidation, allOf, anyOf, not) before v1.0; update call sites and docs.
+
+- forbidKeys
+
+  Explicit key deny-listing on AssociativeValidator/ObjectValidator: forbidKeys(array $keys, ?string $message = null).
+
+- Performance benchmarking
+
+  Establish baseline for hot paths (validate, tryValidate, schema validation); document how to run and interpret results.
+
+- Docs refresh
+
+  Update examples, ensure API reference matches current surface, add migration notes where relevant.

docs/api-reference/validator-factory.md

@@ -573,6 +573,48 @@ $validator->validate([]); // Throws ValidationException
 
 ---
 
+#### `uniqueField(string $fieldName, ?string $message = null): ArrayValidator`
+
+Validates that a nested field is unique across all array items. Produces field-level error paths (e.g., `symlinks.2.destination`) automatically. Items where the field is null or missing are skipped. Works with associative arrays and objects.
+
+```php
+$schema = Validator::isAssociative([
+    'symlinks' => Validator::isArray()
+        ->items(Validator::isAssociative([
+            'source' => Validator::isString()->default('.'),
+            'destination' => Validator::isString()->required(),
+        ]))
+        ->uniqueField('destination')
+        ->required(),
+]);
+
+$result = $schema->validate([
+    'symlinks' => [
+        ['destination' => '/var/www/public'],
+        ['destination' => '/var/www/storage'],
+    ],
+]); // Valid
+
+// Duplicate destination throws ValidationException with path 'symlinks.2.destination'
+$schema->validate([
+    'symlinks' => [
+        ['destination' => '/same'],
+        ['destination' => '/same'],
+    ],
+]);
+```
+
+**Parameters:**
+
+- `$fieldName`: The field name to check for uniqueness
+- `$message` (optional): Custom error message for duplicate values
+
+**Returns:** `ArrayValidator` instance with unique-field validation enabled.
+
+**See Also:** [Array Validation Guide - Cross-Item Validation](../guides/array-validation.md#cross-item-validation)
+
+---
+
 ## Universal Methods
 
 All validators created by the factory methods inherit these universal methods from `FieldValidator`:

docs/guides/array-validation.md

@@ -477,11 +477,9 @@ try {
 
 ## Cross-Item Validation
 
-For validations that need to check relationships across multiple array items (like uniqueness), use `satisfies()` on the array validator. To attach errors to specific fields within items, use a nested error structure.
+### uniqueField() for Uniqueness
 
-### Uniqueness Validation with Field-Level Errors
-
-When validating uniqueness of a nested field (e.g., `destination` in each symlink), structure errors to attach them to the specific field:
+Use `uniqueField()` to validate that a nested field is unique across all array items. It produces field-level error paths (e.g., `symlinks.2.destination`) automatically. Items where the field is null or missing are skipped.
 
 ```php
 $schema = Validator::isAssociative([
@@ -490,50 +488,7 @@ $schema = Validator::isAssociative([
             'source' => Validator::isString()->default('.'),
             'destination' => Validator::isString()->required(),
         ]))
-        ->satisfies(
-            function ($symlinks, $key, $input) {
-                // Extract all destination values with their indices
-                $destinations = [];
-                foreach ($symlinks as $index => $symlink) {
-                    if (isset($symlink['destination'])) {
-                        $dest = $symlink['destination'];
-                        if (!isset($destinations[$dest])) {
-                            $destinations[$dest] = [];
-                        }
-                        $destinations[$dest][] = $index;
-                    }
-                }
-
-                // Check for duplicates
-                $duplicates = [];
-                foreach ($destinations as $dest => $indices) {
-                    if (count($indices) > 1) {
-                        $duplicates[$dest] = $indices;
-                    }
-                }
-
-                if (empty($duplicates)) {
-                    return true;
-                }
-
-                // Nested error structure: [index => [field => [message]]]
-                // This creates field-level error paths: 'symlinks.2.destination'
-                $errors = [];
-                foreach ($duplicates as $dest => $indices) {
-                    // Mark all but the first occurrence as duplicates
-                    foreach (array_slice($indices, 1) as $idx) {
-                        $errors[$idx] = [
-                            'destination' => [
-                                "Destination '{$dest}' is not unique (also used at index {$indices[0]})"
-                            ]
-                        ];
-                    }
-                }
-
-                throw new ValidationException($errors);
-            },
-            'All destinations must be unique'
-        )
+        ->uniqueField('destination')
         ->required(),
 ]);
 
@@ -550,12 +505,20 @@ try {
 } catch (ValidationException $e) {
     $flattened = $e->getFlattenedErrors();
     // [
-    //     ['path' => 'symlinks.2.destination', 'message' => "Destination '/same/path' is not unique (also used at index 0)"]
+    //     ['path' => 'symlinks.2.destination', 'message' => "Value '/same/path' is not unique (also used at index 0)"]
     // ]
 }
 ```
 
-**Key Pattern:** Structure errors as `[arrayIndex => [fieldName => [errorMessage]]]` to get field-level error paths. The flattening logic automatically builds paths like `symlinks.2.destination` from this nested structure.
+Custom message:
+
+```php
+->uniqueField('destination', 'Destination must be unique across all symlinks')
+```
+
+### Custom Cross-Item Validation with satisfies()
+
+For validations beyond uniqueness (ordering, dependencies, custom logic), use `satisfies()` on the array validator. Structure errors as `[arrayIndex => [fieldName => [errorMessage]]]` to get field-level paths.
 
 ### Simple Uniqueness Check (Array-Level Error)
 

docs/guides/custom-validation.md

@@ -294,9 +294,9 @@ $validator = Validator::isString()
 
 For validations that need to check relationships across multiple array items (like uniqueness, ordering, or dependencies), use `satisfies()` on the array validator. This runs **after** item validation, so you receive the validated data structure.
 
-### Uniqueness Validation with Field-Level Errors
+### Uniqueness: uniqueField() (Convenience Method)
 
-When validating uniqueness of a nested field across array items, structure errors to attach them to specific fields within items:
+For simple field uniqueness across items, use `uniqueField()`:
 
 ```php
 $schema = Validator::isAssociative([
@@ -305,42 +305,7 @@ $schema = Validator::isAssociative([
             'id' => Validator::isInt()->required(),
             'name' => Validator::isString()->required(),
         ]))
-        ->satisfies(
-            function ($items, $key, $input) {
-                // Check uniqueness of 'id' field
-                $ids = [];
-                foreach ($items as $index => $item) {
-                    if (isset($item['id'])) {
-                        $id = $item['id'];
-                        $ids[$id][] = $index;
-                    }
-                }
-
-                $duplicates = [];
-                foreach ($ids as $id => $indices) {
-                    if (count($indices) > 1) {
-                        $duplicates[$id] = $indices;
-                    }
-                }
-
-                if (empty($duplicates)) {
-                    return true;
-                }
-
-                // Nested error structure: [index => [field => [message]]]
-                // This creates field-level error paths: 'items.2.id'
-                $errors = [];
-                foreach ($duplicates as $id => $indices) {
-                    foreach (array_slice($indices, 1) as $idx) {
-                        $errors[$idx] = [
-                            'id' => ["ID {$id} is not unique (also used at index {$indices[0]})"]
-                        ];
-                    }
-                }
-
-                throw new ValidationException($errors);
-            }
-        )
+        ->uniqueField('id'),
 ]);
 
 $input = [
@@ -356,12 +321,12 @@ try {
 } catch (ValidationException $e) {
     $flattened = $e->getFlattenedErrors();
     // [
-    //     ['path' => 'items.2.id', 'message' => 'ID 1 is not unique (also used at index 0)']
+    //     ['path' => 'items.2.id', 'message' => "Value '1' is not unique (also used at index 0)"]
     // ]
 }
 ```
 
-**Key Pattern:** Structure errors as `[arrayIndex => [fieldName => [errorMessage]]]` to get field-level error paths. The error flattening logic automatically builds paths like `items.2.id` from this nested structure.
+Use `satisfies()` when you need custom duplicate logic, custom messages per value, or cross-field uniqueness. See the [Array Validation Guide](array-validation.md#custom-cross-item-validation-with-satisfies) for the manual `satisfies()` pattern.
 
 ### Other Cross-Item Validations
 

docs/guides/error-handling.md

@@ -261,47 +261,15 @@ try {
 
 **Cross-Item Validation Errors (Field-Level):**
 
-For cross-item validations (like uniqueness) that need to attach errors to specific fields within items, use nested error structure:
+For uniqueness of a nested field, use `uniqueField()` -- it produces the nested error structure and field-level paths automatically:
 
 ```php
 $schema = Validator::isAssociative([
     'symlinks' => Validator::isArray()
         ->items(Validator::isAssociative([
             'destination' => Validator::isString()->required(),
         ]))
-        ->satisfies(
-            function ($symlinks) {
-                // Check uniqueness
-                $destinations = [];
-                foreach ($symlinks as $index => $item) {
-                    $dest = $item['destination'] ?? null;
-                    if ($dest) {
-                        $destinations[$dest][] = $index;
-                    }
-                }
-
-                $duplicates = [];
-                foreach ($destinations as $dest => $indices) {
-                    if (count($indices) > 1) {
-                        $duplicates[$dest] = $indices;
-                    }
-                }
-
-                if (empty($duplicates)) return true;
-
-                // Nested structure: [index => [field => [message]]]
-                // Flattens to 'symlinks.2.destination'
-                $errors = [];
-                foreach ($duplicates as $dest => $indices) {
-                    foreach (array_slice($indices, 1) as $idx) {
-                        $errors[$idx] = [
-                            'destination' => ["'{$dest}' is not unique"]
-                        ];
-                    }
-                }
-                throw new ValidationException($errors);
-            }
-        )
+        ->uniqueField('destination'),
 ]);
 
 try {
@@ -315,12 +283,12 @@ try {
 } catch (ValidationException $e) {
     $flattened = $e->getFlattenedErrors();
     // [
-    //     ['path' => 'symlinks.2.destination', 'message' => "'/path1' is not unique"]
+    //     ['path' => 'symlinks.2.destination', 'message' => "Value '/path1' is not unique (also used at index 0)"]
     // ]
 }
 ```
 
-**Key Pattern:** Structure errors as `[arrayIndex => [fieldName => [errorMessage]]]` to get field-level error paths in flattened output.
+For custom cross-item logic, use `satisfies()` and structure errors as `[arrayIndex => [fieldName => [errorMessage]]]` to get field-level paths in flattened output.
 
 ## Error Message Customization
 

llms.txt

@@ -136,9 +136,10 @@ notEmpty(?string $message = null): static
 minItems(int $min, ?string $message = null): static
 maxItems(int $max, ?string $message = null): static
 contains(mixed|FieldValidator $valueOrValidator, ?string $message = null): static
+uniqueField(string $fieldName, ?string $message = null): static
 ```
 
-**Cross-Item Validation:** Use `satisfies()` on array validator for uniqueness/relationships. Structure errors as `[index => [field => [message]]]` to get field-level paths (e.g., `symlinks.2.destination`). Runs after item validation, receives validated data structure.
+**Cross-Item Validation:** `uniqueField()` validates a nested field is unique across items with field-level error paths (e.g., `symlinks.2.destination`). For custom cross-item logic, use `satisfies()` directly -- structure errors as `[index => [field => [message]]]` for field-level paths. Both run after item validation and receive validated data.
 
 ### AssociativeValidator / ObjectValidator