feat(validator)!: add structured ValidationError model with stable codes

- Add ValidationError value object and ValidationCode catalog
- Emit codes and params from built-in validators; expose getStructuredErrors() on ValidationException
- Extend satisfies() with optional code and params arguments
- Update docs and tests for structured error handling

BREAKING CHANGE: tryValidate() now returns a flat list of ValidationError objects as its third tuple element instead of nested message strings. ValidationException::__construct() now accepts ValidationError[]; getErrors() still returns the legacy nested message array.

Author: lemmon

AGENTS.md

@@ -13,7 +13,7 @@ Core validation logic lives in `src/Lemmon/Validator/`. Tests in `tests/` follow
 ## Architecture
 
 - **Namespace:** `Lemmon\Validator` (runtime), `Lemmon\Tests` (tests)
-- **Core:** `Validator` static factory; `FieldValidator` base; `ValidationException` for errors
+- **Core:** `Validator` static factory; `FieldValidator` base; `ValidationException` for errors; `ValidationError` value object (path/code/message/params) is the structured-error source of truth (`getStructuredErrors()`); `ValidationCode` stable-code catalog
 - **Validators:** `isString`, `isInt`, `isFloat`, `isBool`, `isArray`, `isAssociative`, `isObject`
 - **Shared:** `NumericConstraintsTrait` (min, max, multipleOf, etc.); `PipelineType` enum; `PipelineStep` value object (internal pipeline entry); `PipelineContext` (internal per-run type context threaded through the pipeline); variant enums `IpVersion`, `Base64Variant`, `UuidVariant` for format methods
 - **String formats:** email, URL, UUID, IP, hostname, domain, time, base64, hex, regex, datetime, date

CHANGELOG.md

@@ -6,10 +6,15 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- Structured error model. `ValidationException::getStructuredErrors()` returns a flat list of new `ValidationError` value objects, each with `getPath()` (dotted, `''` at root), `getCode()` (a stable code from the new `ValidationCode` catalog, e.g. `STRING_TOO_SHORT`, `INVALID_TYPE`, `REQUIRED`), `getMessage()`, and `getParams()` (e.g. `['min' => 5]`). `ValidationError` is `JsonSerializable`. All built-in validators now emit codes and params; messages support `{name}` placeholder substitution from params
+- `satisfies()` accepts two optional trailing arguments: `?string $code` (defaults to `CUSTOM`) and `array $params` for structured error codes and message placeholders on custom rules
 - `enum()` on `FieldValidator` now accepts PHP `UnitEnum` (non-backed enums): the value must be an instance of the enum or a string equal to one of the case names; `BackedEnum` behavior is unchanged (int or string backed values via `tryFrom()`)
 
 ### Changed
 
+- **BREAKING:** the third element of the `tryValidate()` tuple is now a flat list of `ValidationError` objects (previously a nested array of message strings). `ValidationException::flattenErrors()` now accepts this list. `ValidationException::getErrors()` still returns the legacy nested message array (back-compatible) and `getFlattenedErrors()` is unchanged
+- **BREAKING:** `ValidationException::__construct()` now takes a list of `ValidationError` objects instead of a raw error array (affects only code that constructs the exception directly)
+
 - Internal refactor (no public API or behavior change): `Validator::allOf()`, `anyOf()`, and `not()` now build on a new concrete `MixedValidator` base instead of repeating an inline anonymous class; validator pipeline steps are now a typed `PipelineStep` value object (internal) instead of an associative array, simplifying `FieldValidator::__clone()`
 - Internal refactor (no public API or behavior change): the `transform()`/`pipe()` type context now lives in a per-run `PipelineContext` object created in `tryValidate()` instead of a mutable `currentType` property on the validator; pipeline operations are now stateless static closures, so cloning no longer rebinds them and validator instances hold no transient state during a run (safe for reuse and reentrancy)
 

README.md

@@ -43,6 +43,7 @@ Rather than reimplementing every possible transformation or validation rule, Lem
 - **Type-safe validation** for strings, integers, floats, arrays, and objects
 - **Fluent, chainable API** with guaranteed execution order -- methods execute exactly as written in the chain
 - **Schema-level error aggregation** with fail-fast behavior per field for clear, early feedback
+- **Structured errors** - `getStructuredErrors()` returns `ValidationError` objects with a stable `code` (see `ValidationCode`), dotted `path`, `message`, and `params` for programmatic handling and i18n; match on codes rather than message text
 - **API-friendly flattened errors** with field paths for easy frontend integration (`getFlattenedErrors()`, `ValidationException::flattenErrors()`)
 - **Intuitive custom validation** with `satisfies()` method and optional error messages
 - **Single-value validation** with `const()` for exact value matching (available on all validators)

docs/api-reference/validator-factory.md

@@ -293,7 +293,8 @@ try {
 if ($valid) {
     echo 'Valid email: ' . $data;
 } else {
-    echo 'Errors: ' . implode(', ', $errors);
+    // $errors is a list of ValidationError objects
+    echo 'Errors: ' . implode(', ', array_map(fn($e) => $e->getMessage(), $errors));
 }
 ```
 

docs/examples/form-validation.md

@@ -101,13 +101,11 @@ if ($_SERVER['REQUEST_METHOD'] === 'POST') {
 }
 ?>
 
-<!-- Display errors in template -->
+<!-- Display errors in template ($errors is a list of ValidationError objects) -->
 <?php if (isset($errors)): ?>
     <div class="alert alert-danger">
-        <?php foreach ($errors as $field => $fieldErrors): ?>
-            <?php foreach ($fieldErrors as $error): ?>
-                <div><?= htmlspecialchars($error) ?></div>
-            <?php endforeach; ?>
+        <?php foreach ($errors as $error): ?>
+            <div><?= htmlspecialchars($error->getMessage()) ?></div>
         <?php endforeach; ?>
     </div>
 <?php endif; ?>
@@ -844,12 +842,9 @@ function formatErrorsForDisplay(array $errors): array
 {
     $formatted = [];
 
-    foreach ($errors as $field => $fieldErrors) {
-        $fieldName = ucfirst(str_replace('_', ' ', $field));
-
-        foreach ($fieldErrors as $error) {
-            $formatted[] = "{$fieldName}: {$error}";
-        }
+    foreach ($errors as $error) {
+        $fieldName = ucfirst(str_replace(['_', '.'], [' ', ' '], $error->getPath()));
+        $formatted[] = "{$fieldName}: {$error->getMessage()}";
     }
 
     return $formatted;

docs/getting-started/basic-usage.md

@@ -62,7 +62,8 @@ try {
 
 ### `tryValidate()` - Tuple-based
 
-Returns a tuple `[bool $valid, mixed $data, array $errors]`:
+Returns a tuple `[bool $valid, mixed $data, ?array $errors]`, where `$errors` is a flat list of
+`ValidationError` objects (or `null` on success):
 
 ```php
 $validator = Validator::isString()->email();
@@ -72,7 +73,8 @@ $validator = Validator::isString()->email();
 if ($valid) {
     echo "Valid email: " . $data;
 } else {
-    echo "Errors: " . implode(', ', $errors);
+    echo "Errors: " . implode(', ', array_map(fn($e) => $e->getMessage(), $errors));
+    // Each error also exposes getPath(), getCode(), and getParams()
 }
 ```
 
@@ -277,9 +279,9 @@ $validator = Validator::isString()
 
 [$valid, $data, $errors] = $validator->tryValidate('ab');
 
-// $errors might contain:
+// $errors is a flat list of ValidationError objects:
 // [
-//     'Value must be at least 5 characters long'
+//     ValidationError(path: '', code: 'STRING_TOO_SHORT', message: 'Value must be at least 5 characters long'),
 // ]
 ```
 

docs/getting-started/core-concepts.md

@@ -40,7 +40,7 @@ All validators extend `FieldValidator`, which provides:
 ### Core Validation Methods
 
 - `validate(mixed $value): mixed` - Throws exception on failure
-- `tryValidate(mixed $value): array` - Returns `[bool, mixed, array]`
+- `tryValidate(mixed $value): array` - Returns `[bool $valid, mixed $data, ?array $errors]`, where `$errors` is a list of `ValidationError` objects
 
 ### Common Configuration
 
@@ -342,7 +342,7 @@ $validator = Validator::isString()
 // Stops at the first failing rule in this chain:
 [$valid, $data, $errors] = $validator->tryValidate('ab');
 // $errors = [
-//     'Value must be at least 5 characters long'
+//     ValidationError(path: '', code: 'STRING_TOO_SHORT', message: 'Value must be at least 5 characters long'),
 // ]
 ```
 

docs/guides/array-validation.md

@@ -428,10 +428,9 @@ $validator = Validator::isArray()->items(Validator::isInt()->coerce());
 
 if (!$valid) {
     echo "Validation failed:\n";
-    print_r($errors);
-    // Output:
+    // $errors is a flat list of ValidationError objects:
     // [
-    //     '1' => ['Value must be an integer']
+    //     ValidationError(path: '1', code: 'INVALID_TYPE', message: 'Value must be an integer'),
     // ]
 
     // Flattened errors preserve array indices
@@ -519,7 +518,7 @@ Custom message:
 
 ### 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.
+For validations beyond uniqueness (ordering, dependencies, custom logic), use `satisfies()` on the array validator. Throw a `ValidationException` of `ValidationError` objects whose `path` is `"{index}.{field}"` to get field-level paths.
 
 ### Simple Uniqueness Check (Array-Level Error)
 

docs/guides/custom-validation.md

@@ -264,12 +264,34 @@ $validator = Validator::isString()
 
 [$valid, $data, $errors] = $validator->tryValidate('short');
 
-// $errors will contain:
+// $errors is a flat list of ValidationError objects; the chain stops at the first failure:
 // [
-//     'Value must be at least 8 characters long'
+//     ValidationError(path: '', code: 'STRING_TOO_SHORT', message: 'Value must be at least 8 characters long'),
 // ]
 ```
 
+## Custom Error Codes and Placeholders
+
+`satisfies()` accepts two optional trailing arguments: a stable `$code` and a `$params` map. The
+code lets integrators handle the error programmatically (it defaults to `CUSTOM`), and params double
+as `{name}` placeholders substituted into the message:
+
+```php
+$validator = Validator::isString()->satisfies(
+    fn($value) => strlen($value) >= 12,
+    'Password must be at least {min} characters',
+    'PASSWORD_TOO_SHORT',
+    ['min' => 12],
+);
+
+[$valid, $data, $errors] = $validator->tryValidate('weak');
+// $errors[0]->getCode()    === 'PASSWORD_TOO_SHORT'
+// $errors[0]->getMessage() === 'Password must be at least 12 characters'
+// $errors[0]->getParams()  === ['min' => 12]
+```
+
+See the [Error Handling Guide](error-handling.md#structured-errors) for the full structured-error model.
+
 ## Advanced Patterns
 
 ### Using External Validation Libraries