@jarenjs/validate 0.9.2 → 0.34.2

package/ARCHITECTURE.md

@@ -27,6 +27,7 @@ The validator embraces these architectural principles:
 | `packages/validate/src/index.js` | Main validator classes (`JarenValidator`, `ValidationRoot`, `ValidationObject`) |
 | `packages/validate/src/traverse.js` | Schema traversal and ref resolution (`storeSchemaIdsInMap`, `restoreSchemaRefsInMap`) |
 | `packages/validate/src/schema.js` | Schema compilation dispatcher (`compileSchemaObject`) |
+| `packages/validate/src/messages.js` | Error conversion, message catalogs, the `errorMessage` keyword specs (`ValidationError`, `messagesEn`, `localizeErrors`) |
 | `packages/validate/src/array.js` | Array validation logic |
 | `packages/validate/src/object.js` | Object validation logic |
 | `packages/validate/src/string.js` | String validation logic |
@@ -84,17 +85,30 @@ The validator operates in four distinct phases that cleanly separate concerns:
 **Entry Point**: `JarenValidator.addSchema(schema, key)`
 
 **Flow**:
-```
-addSchema(schema, key)
-  ├── Store schema under key (and alt key with/without #)
-  └── #traverseAndStoreIds(baseUri, schema)
-        └── storeSchemaIdsInMap(schemasMap, baseUri, schema)
-              ├── Store root schema under baseUri
-              └── BFS traverse schema structure:
-                    ├── On $id: Store subschema, update baseUri
-                    ├── On $anchor: Store anchor
-                    ├── On $ref: Store null placeholder (mark as ref)
-                    └── On schema objects/arrays: Continue traversal
+```mermaid
+flowchart TD
+    A["addSchema(schema, key)"]
+    B["store schema under key<br/>(and the alt key with/without #)"]
+    C["#traverseAndStoreIds(baseUri, schema)"]
+    D["storeSchemaIdsInMap(schemasMap, baseUri, schema)"]
+    E["store the root schema under baseUri"]
+    F{"BFS over the schema structure"}
+    G["$id — store subschema, update baseUri"]
+    H["$anchor — store anchor"]
+    I["$ref — store a null placeholder, marked as a ref"]
+    J["objects / arrays — keep traversing"]
+    A --> B
+    A --> C
+    C --> D
+    D --> E
+    D --> F
+    F --> G
+    F --> H
+    F --> I
+    F --> J
+    N["the placeholder is what lets refs<br/>be added in any order"]
+    I -.- N
+    class N note
 ```
 
 **Key Data Structure**: `#schemas Map<string, schema|null>`
@@ -349,6 +363,16 @@ The compilation context that:
 - Collects validation errors
 - Provides `$ref` resolution services
 
+**Owner threading**: the constructor takes a sixth argument `owner`
+(default `null`), exposed through an `owner` getter, and both construction
+sites in `index.js` pass the owning `JarenValidator` for it. This lets
+`query-keyword.js` hand that instance to `createTypeTestCompiler`, so the
+schema literals inside a `$query` document (`$valid`/`$assert`/`$as`)
+resolve their `$ref`s against the owner's `addSchema` registrations. The
+resulting ESM cycle — `index.js` → `schema.js` → `query-keyword.js` →
+`query.js` → `index.js` — is benign: `query.js` only *reads* the hoisted
+`JarenValidator` declaration at call time, never at module-evaluation time.
+
 ### ValidationObject
 
 Represents a single schema location with its compiled validator:
@@ -576,6 +600,14 @@ flowchart TB
     B5 --> C
 ```
 
+**Compile-failure fallback**: the ref compilers of `@jarenjs/json`
+(`compileDataRef` for the `data` keyword, `compileRelativeJSONPointer` for
+`$data`) *throw* on a malformed reference. `data.js` and `dollar-data.js`
+each wrap the compile in a `compileRefResolver` try/catch that falls back to
+an always-`JSONPOINTER_NOTHING` resolver. A malformed `$data`/`data`
+reference therefore validates as "not found" — the keyword asserts nothing —
+instead of throwing at compile time, keeping the lax keyword semantics.
+
 ---
 
 ## Error Handling Architecture
@@ -593,10 +625,10 @@ flowchart LR
     F --> G[All validators complete]
     G --> H{collectErrors?}
 
-    H -->|true| I[Convert to ValidationError]
+    H -->|true| I[convertInternalErrors - messages.js]
     H -->|false| J[Return boolean only]
 
-    I --> K[Add human-readable messages]
+    I --> K[Extract params, resolve msgid,<br/>match errorMessage registry,<br/>render through catalog]
     K --> L[Return {valid, errors}]
 
     style C fill:#9f9
@@ -604,6 +636,29 @@ flowchart LR
     style L fill:#9f9
 ```
 
+### Report-Time Messages (messages.js)
+
+Conversion is structured-first, render-late (the normative spec is
+[docs/ERROR-MESSAGES.md](./docs/ERROR-MESSAGES.md)):
+
+- Every public `ValidationError` carries a stable `msgid` (the matched
+  `errorMessage` spec's `$msgid`, else the `$query` runtime code, else the
+  keyword) plus raw `params`; `instancePath` is a straight read of the
+  first meta argument every handler call site passes (the
+  handler-contract invariant), behind a charCode guard that yields `''`
+  rather than ever a wrong path.
+- The `errorMessage` keyword compiles at schema compile time into a
+  registry on `ValidationRoot` (`registerErrorMessage`) — no validator
+  closure is emitted and the single-keyword fast paths stay eligible (the
+  key count excludes it). Matching happens only over the failed set:
+  nearest registered ancestor by segment-aware prefix; map-form entries
+  and `_` apply at the node itself, the string form covers the subtree.
+- Human text renders through catalogs — plain objects of closures /
+  template strings (`messagesEn` built in; packs in `@jarenjs/locales`).
+  `localizeErrors(errors, catalog)` re-renders post hoc from
+  `msgid` + `params`; the `messages: false` option skips rendering
+  entirely (`message: ''`).
+
 ### Error Handler Creation
 
 ```mermaid
@@ -973,8 +1028,8 @@ console.log('Resolving ref:', ref, 'against baseUri:', baseUri);
 
 For broader context on how this package fits into the JarenJS ecosystem:
 
-- **Project-wide Architecture**: See `/ARCHITECTURE.md` at the project root
-- **Developer Guide**: See `/HOWTO.md` at the project root
+- **Project-wide Architecture**: See `docs/ARCHITECTURE.md`
+- **Developer Guide**: See `docs/HOWTO.md`
 - **Core Package**: Depends on `@jarenjs/core` for fundamental utilities and `@jarenjs/json` for the JSON addressing standards
 
 ---
@@ -983,7 +1038,8 @@ For broader context on how this package fits into the JarenJS ecosystem:
 
 | File | Purpose | Key Exports |
 |------|---------|-------------|
-| `index.js` | Public API | `JarenValidator`, `ValidationOptions`, `ValidatorOptions`, `ValidationError` |
+| `index.js` | Public API | `JarenValidator`, `ValidationOptions`, `ValidatorOptions` |
+| `messages.js` | Error conversion & i18n | `ValidationError`, `convertInternalErrors`, `messagesEn`, `compileMessageTemplate`, `compileMessageCatalog`, `renderErrorMessage`, `localizeErrors`, `compileErrorMessageSpec` |
 | `schema.js` | Schema compilation | `compileSchemaObject` |
 | `traverse.js` | Schema traversal | `TraverseOptions`, `storeSchemaIdsInMap`, `resolveRefSchemaDeep` |
 | `tools.js` | Shared utilities | `isBoolOrObjectClass`, `hasSchemaRef`, `createIsSchemaTypeHandler` |
@@ -1001,6 +1057,7 @@ For broader context on how this package fits into the JarenJS ecosystem:
 | `dollar-data.js` | $data keyword | `compileDollarDataSchema` |
 | `unevaluated.js` | unevaluated* keywords | `wrapUnevaluated` |
 | `dynamic-ref.js` | Dynamic scope helpers | `collectDynamicAnchorsDeep`, `hasRecursiveAnchor`, `getDynamicAnchorName` |
+| `query-keyword.js` | `$query` extension keyword | `compileQuerySchema` |
 
 ---
 
@@ -1028,12 +1085,19 @@ For broader context on how this package fits into the JarenJS ecosystem:
 
 ### 3. Lazy Error Generation
 
-**Decision**: Only create error objects when `skipErrors` is false.
+**Decision**: Only create error objects when `skipErrors` is false, and
+only produce human-readable text at report time (`convertInternalErrors`
+in messages.js), over the already-failed set, from a `msgid` + `params`
+pair through a message catalog.
 
 **Rationale**:
 - Most production use cases only need boolean results
 - Error object creation is expensive
 - Reduces GC pressure during high-throughput validation
+- Structured-first errors make locale a report-time choice: switching
+  language (`localizeErrors`, `@jarenjs/locales`) never recompiles a
+  validator, and the `errorMessage` keyword resolves against a registry
+  with zero validation-time cost (see docs/ERROR-MESSAGES.md)
 
 ### 4. Dual Data Reference Systems
 

package/README.md

@@ -193,7 +193,7 @@ See also:
 
   Both absolute JSON Pointers (e.g., `/A`, `/limits/min`) and relative JSON Pointers (e.g., `0/parent`, `1/sibling`) are supported.
 
-- `$data` | Ajv-style instance references (`{ "minimum": { "$data": "1/limit" } }`) — supports every keyword the `data` list above supports, plus `uniqueItems` and `required`. Refs compile once at schema compile time through the compiled pointer engine of `@jarenjs/json`.
+- `$data` | Ajv-style instance references (`{ "minimum": { "$data": "1/limit" } }`) — supports every keyword the `data` list above supports, plus `uniqueItems` and `required`. Takes the same three reference forms: empty for the whole instance, an absolute JSON Pointer (`/limit`), or a Relative JSON Pointer (`1/limit`). Refs compile once at schema compile time through the compiled pointer engine of `@jarenjs/json`, and a reference that cannot be compiled **fails the compile** rather than quietly resolving to nothing — a constraint that disables itself is worse than a rejected schema.
 
 - `$query` | Jaren's cross-field assertion keyword — see [below](#query--cross-field-assertions)
 
@@ -202,7 +202,7 @@ See also:
 - ❌ strict
 - ❌ strictFormat
 - ❌ strictTuple
-- ❌ errorMessage
+- errorMessage | author-supplied messages that override text (never structure) — see [Error messages & i18n](#error-messages--i18n)
 - definitions | used by initial schema traversal _deprecated in `draft2019`_
 - $defs | used by initial schema traversal _new `draft2019`_
 - components | _(OpenAPI)_
@@ -323,7 +323,13 @@ Semantics and composition:
   keyword: under `properties`/`items` the query's `$` is that location's
   value, `$path` its pointer (`/lines/0`, ...), `$root` the whole document.
 - A bare JSONPath string is the degenerate query: `{ "$query": "$.approved" }`
-  asserts the EBV of that member (missing → empty sequence → false).
+  asserts the **EBV** of that member, not its mere existence: existence would
+  let `$.approved` pass on a literal `false`, exactly the case the constraint
+  means to reject (missing → empty sequence → false either way).
+- `$query` is a **validation keyword**, so under 2019-09 and 2020-12 it
+  asserts as a sibling of `$ref` (both apply together). Under draft-07 the
+  `$ref`-overrides-siblings rule stands, so a `$query` written beside a `$ref`
+  is ignored on that node.
 - Query **runtime** errors (`JQ2xxx` — e.g. arithmetic on a non-number, the
   EBV of a multi-item result) are validation **failures**, never throws; in
   `collectErrors` mode the error params carry the `code` and the query
@@ -331,10 +337,461 @@ Semantics and composition:
   `root`/`path` fail fast at `compile()`.
 - Schema literals inside the query (`$valid`/`$assert`/`$as`,
   QUERY-FORMAT §8.11) compile against the **same validator instance**, so
-  their `$ref`s resolve to your `addSchema` registrations.
+  their `$ref`s resolve to your `addSchema` registrations. The bridge
+  (`createTypeTestCompiler`) accepts nothing (a fresh default instance), a
+  `JarenValidator` instance, or a zero-arg factory, and probes the compiled
+  validator's return shape **once per schema literal** — so even a
+  `collectErrors` instance is unwrapped into a boolean predicate.
+
+## Compatibility settings
+
+Five options decide answers that differ between validators, between JSON
+Schema drafts, or between Jaren and the library you are migrating from. Each
+one is a deliberate default, and each one is worth setting explicitly in a
+shared factory rather than inheriting.
+
+| Option | Default | What it decides |
+|---|---|---|
+| `collectErrors` | `false` | Whether the compiled validator returns a boolean or `{ valid, errors }` |
+| `skipErrors` | `!collectErrors` | Whether validation stops at the first failure |
+| `useGrapheme` | **`true`** | Whether `minLength`/`maxLength` count grapheme clusters or UTF-16 code units |
+| `formatAssertion` | auto by draft | Whether `format` asserts or only annotates |
+| `contentValidation` | auto by draft | Whether `contentEncoding`/`contentMediaType` assert |
+
+### The return shape is `collectErrors`
+
+`collectErrors` is the *only* switch between the two return shapes, and it is
+off by default:
+
+```javascript
+new JarenValidator().compile(schema)(data);
+// => true | false
+
+new JarenValidator({ collectErrors: true }).compile(schema)(data);
+// => { valid: false, errors: [ /* ValidationError */ ] }
+```
+
+Setting `collectErrors: true` implies `skipErrors: false` (collecting errors
+means recording them), so you do not need to set both. Set `skipErrors`
+yourself only to keep first-failure short-circuiting while still collecting.
+
+There is **no `validator.errors` property**. Errors arrive in the returned
+object and nowhere else, which is what makes a compiled validator reentrant
+and safe to share across concurrent requests.
+
+Each `ValidationError` carries six fields:
+
+```javascript
+{
+  keyword: 'format',                 // the JSON Schema keyword that failed
+  instancePath: '/email',            // RFC 6901 JSON Pointer into the DATA
+  schemaPath: 'https://…#/properties/email',  // absolute URI into the SCHEMA
+  params: { format: 'email' },       // raw structured values, never prose
+  msgid: 'format',                   // stable catalog key for i18n
+  message: 'must match format "email"'
+}
+```
+
+Two notes for anyone diffing this against another validator's output. The
+data location is `instancePath`, a **JSON Pointer string** — not the dotted
+`dataPath` of Ajv v6, and not an array path. `parseJSONPointerPath` from
+[`@jarenjs/json`](../json/README.md) converts it to the `(string|number)[]`
+path shape that Zod's `issue.path` and most diffing tools use, narrowing
+canonical array indexes to numbers:
+
+```javascript
+import { parseJSONPointerPath } from '@jarenjs/json';
+
+parseJSONPointerPath('/items/0/id');   // ['items', 0, 'id']
+```
+
+And for `additionalProperties: false`, Jaren points `instancePath` at the
+offending member (`/nested/extra`) where Ajv points at the parent object —
+deliberate, and spec-truer.
+
+**Collected errors are exhaustive across independent keywords.** Every
+keyword that can fail independently reports its own fault, rather than the
+first failure hiding the rest: keyword groups on one node (`enum` beside
+`minLength`), `minProperties` beside `required`, a numeric bound beside
+`multipleOf`, `minItems` beside `uniqueItems` and beside failing items, every
+`allOf` branch, independent applicator groups, and every absent `required`
+property. Boolean mode still stops at the first failure — that is the whole
+point of it — so the two modes deliberately differ in how much work they do:
+
+```javascript
+const contract = {
+  type: 'object',
+  properties: { slug: { type: 'string', minLength: 3, pattern: '^[a-z]+$' } },
+  required: ['name', 'slug'],
+};
+
+collecting.compile(contract)({ slug: '!' }).errors;
+// required at '', minLength at '/slug', pattern at '/slug'  — three issues
+```
+
+**A speculative applicator never reports.** An `anyOf`/`oneOf` branch that was
+not the one that matched, the subschema of a `not`, an `if` condition, and a
+`contains` candidate that is not the match are all probes — the document was
+never required to satisfy them, so their failures are rolled back rather than
+handed to your caller. What survives is what genuinely explains the failure:
+if *no* `anyOf` branch matched, every branch's errors are kept, because then
+they are the reason.
+
+```javascript
+collecting.compile({
+  type: 'string', minLength: 5,
+  anyOf: [{ type: 'number' }, { type: 'string' }],
+})('x').errors;
+// [minLength]  — not a type error from the number branch that was never required
+```
+
+A `required` error points at the **owning object**, not at the absent member
+(there is no location for something that is not there); the missing name is in
+`params.missingProperty`, which is what an adapter appends to build a
+Zod-style path.
+
+### String lengths count graphemes by default
+
+`useGrapheme` defaults to **`true`**, so `minLength`/`maxLength` count
+user-perceived characters. Most other validators — and the JSON Schema
+specification itself — count UTF-16 code units:
+
+```javascript
+const family = '👨‍👩‍👧‍👦';   // 1 grapheme cluster, 11 UTF-16 code units
+
+new JarenValidator().compile({ type: 'string', maxLength: 2 })(family);
+// => true   (1 grapheme)
+
+new JarenValidator({ useGrapheme: false })
+  .compile({ type: 'string', maxLength: 2 })(family);
+// => false  (11 code units)
+```
+
+**If you are migrating from a validator that counts code units, set
+`useGrapheme: false`,** or strings containing emoji, combining marks, flags
+or astral-plane characters will silently change validity at the boundaries.
+Grapheme mode is not expensive — ASCII takes a `str.length` fast path and
+most Unicode takes a code-point count; only cluster-forming strings reach
+`Intl.Segmenter` — so the default is about correctness, not speed, and
+switching to it later is a product decision rather than a performance one.
+
+### `format` and content assertion follow the draft
+
+Both are annotation-only in the drafts that say so, and both take an explicit
+override:
+
+- **`format`** asserts through draft 2019-09 and is annotation-only from
+  draft 2020-12 on, per spec. It also turns on automatically when the
+  schema's meta-schema declares the `format-assertion` vocabulary.
+- **`contentEncoding`/`contentMediaType`** assert through draft-07 and are
+  annotation-only from 2019-09 on.
+
+```javascript
+const schema = { $schema: 'https://json-schema.org/draft/2020-12/schema',
+                 type: 'string', format: 'email' };
+
+new JarenValidator().addFormats(formats.stringFormats)
+  .compile(schema)('nope');                       // => true  (annotation only)
+
+new JarenValidator({ formatAssertion: true }).addFormats(formats.stringFormats)
+  .compile(schema)('nope');                       // => false (asserted)
+```
+
+### Formats are never registered implicitly — and an unregistered one is an error
+
+`@jarenjs/validate` does not depend on `@jarenjs/formats`, so a fresh
+validator has an **empty format registry**. Registering the groups you use is
+the whole setup:
+
+```javascript
+import * as formats from '@jarenjs/formats';
+
+const jaren = new JarenValidator()
+  .addFormats(formats.stringFormats)     // email, uri, uuid, hostname, iban, ...
+  .addFormats(formats.dateTimeFormats)   // date-time, date, time, duration
+  .addFormats(formats.numberFormats)     // int32, double, decimal, ...
+  .addFormats(formats.jsonFormats)       // json-pointer, json-path, regex, ...
+  .addFormats(formats.geoFormats);       // geohash, lat-long, ...
+```
+
+**An unregistered format name asserts nothing, and by default says nothing** —
+that is the specification's rule ("implementations MUST NOT fail validation or
+cease processing due to an unknown format attribute"), and it is the default
+because a library has to be able to compile a schema it did not write. The
+cost is a real trap: a `format: 'date-time'` you believed was checking
+timestamps, checking nothing, and looking exactly like one that works.
+
+**`unknownFormats: 'error'` turns that into a compile-time throw.** Set it for
+schemas you own:
+
+```javascript
+new JarenValidator({ unknownFormats: 'error' })
+  .compile({ type: 'string', format: 'date-time' });
+// => Error: Unknown format 'date-time': no compiler is registered for it,
+//    so this schema would accept every value for that keyword. Register one
+//    (addFormats(dateTimeFormats) …), or pass { unknownFormats: 'ignore' } …
+```
+
+Instance validation is untouched either way — **no data is ever invalidated by
+an unknown format**, so `'error'` stays inside the specification's letter: it
+reports to the schema's *author*, at compile time, where a missing
+registration is a fact about the setup rather than about the data. The
+official suite's `optional/format/unknown.json` (unknown format, assertion
+forced on, everything must validate) passes on the default and is the one
+thing `'error'` would fail, which is why it is opt-in.
+
+This repository sets `'error'` for every schema it ships, and a gate
+(`test/validate/our-schema-formats.test.js`) fails if any of them names a
+format `@jarenjs/formats` does not implement. It is worth copying: the
+published `jaren-query` grammar declared `format: "json-path"` from the day it
+was written, nothing that compiled it registered `jsonFormats`, and so no path
+string was ever checked by that keyword. Nothing failed. That is the shape of
+this bug.
+
+Where **not** to reach for `'error'`: a schema a user hands you. Refusing to
+compile a stranger's valid schema over a format you happen not to implement is
+your problem presented as theirs — this repo keeps the default for the
+validator playground's input and for project files in the studio, and uses
+`'error'` only for its own grammars. `@jarenjs/ai`'s ledger is the other
+exception: it cannot depend on `@jarenjs/formats` at all, so it stays on the
+default and puts a `pattern` beside the `format` to do the enforcing.
+
+Two things `'error'` deliberately leaves alone. It does not fire where
+`format` is annotation-only anyway (draft 2020-12 without the format-assertion
+vocabulary) — nothing is lost there, so there is nothing to report. And
+**meta-schemas** are exempt: every JSON Schema meta-schema declares
+`format: "uri-reference"` on `$id`, and nobody registers formats in order to
+check that a *schema* is well-formed, so `addMetaSchema` compiles with
+`unknownFormats: 'ignore'` regardless.
+
+Registering a format with something that is **not a compiler** throws under
+either setting, because that mistake is never intentional:
+
+```javascript
+new JarenValidator().addFormats(formats.formatTesters)   // testers, not compilers
+  .compile({ type: 'string', format: 'email' });
+// => Error: Format 'email' failed to compile: … Register the format COMPILERS
+//    (stringFormats, dateTimeFormats, …) rather than the raw testers.
+```
+
+`formatTesters` and `stringFormats` are both objects full of functions, so the
+mistake registers cleanly and then checks nothing. Only the **compilers** take
+`(schemaObj, jsonSchema)` and return the per-value validator.
+
+Registration never overwrites an existing name, so register your own
+overrides *before* a bundled group if you want them to win.
+
+### Recipe: migrating from Zod
+
+Zod counts UTF-16 code units, always reports every issue, and always
+asserts formats. This factory reproduces those three answers:
+
+```javascript
+import { JarenValidator } from '@jarenjs/validate';
+import * as formats from '@jarenjs/formats';
+
+export const jaren = new JarenValidator({
+  collectErrors: true,     // { valid, errors } instead of a boolean
+  useGrapheme: false,      // UTF-16 code units, like Zod's .min()/.max()
+  formatAssertion: true,   // assert format even under draft 2020-12
+  contentValidation: true, // assert contentEncoding/contentMediaType
+})
+  .addFormats(formats.stringFormats)
+  .addFormats(formats.dateTimeFormats);
+```
+
+What this recipe does **not** give you is Zod's output normalization: a
+compiled validator is a pure predicate and never modifies its input. That
+boundary does not move — but the normalization itself ships beside it, as a
+separately compiled pass. See [Normalization](#normalization) below.
+
+## Normalization
+
+Validation answers a question; it does not change your data. When you need
+the *normalized output* that a parse-and-transform library returns —
+materialized defaults, decoded transport values, stripped unknown members —
+compile a normalizer from the same schema and run it first:
+
+```javascript
+import { compileNormalizer } from '@jarenjs/validate/normalize';
+
+const normalize = compileNormalizer(schema, {
+  useDefaults: true,       // fill absent properties from `default`, recursively
+  removeAdditional: true,  // drop members the schema forbids
+  coerceTypes: true,       // '9000' -> 9000 where the schema says integer
+  trimStrings: true,       // '  jaren  ' -> 'jaren'
+});
+
+const shaped = normalize(input);   // a NEW value; `input` is untouched
+const result = validate(shaped);
+```
+
+Every option is **off by default** — each one changes what your data means,
+so each is a decision you make rather than one you inherit.
+`compileNormalizer(schema)` with no options is the identity.
+
+### Per-field control, not just a global switch
+
+`useDefaults`, `coerceTypes` and `trimStrings` each accept a **predicate**
+`(schemaNode) => boolean` in place of a boolean. It runs once per node during
+compilation, so it decides per field and costs nothing at runtime:
+
+```javascript
+const normalize = compileNormalizer(schema, {
+  trimStrings: (node) => node['x-trim'] === true,
+});
+```
+
+This matters more than it looks. A contract typically trims a handful of its
+string fields and must leave the rest byte-for-byte as supplied — a timezone
+name, a deliberately padded identifier, a field whose whitespace is data.
+`trimStrings: true` would quietly rewrite all of them. The predicate reads
+whatever you put in the schema (an `x-` annotation, a `format`, a name
+pattern), which keeps the policy next to the field it governs and portable
+with the schema.
+
+### It never mutates, and it shares what it can
+
+Ajv's `useDefaults`/`coerceTypes` write into the document you hand them.
+This does not: it is a copy-on-write walk, so the input is exactly as it was
+afterwards — you can normalize a frozen document, or keep the original as an
+audit record, without defensive copying.
+
+The other half of that design is identity. A subtree that needs no change is
+returned by reference, and a document that needs no change at all returns the
+input itself:
+
+```javascript
+normalize(alreadyClean) === alreadyClean;   // true
+```
+
+So a no-op costs nothing, and downstream memoization keyed on identity keeps
+working.
+
+### What it walks, and what it deliberately does not
+
+Walked: `properties`, `patternProperties`, `additionalProperties`,
+`items`/`prefixItems`/`additionalItems` (both tuple spellings), same-document
+`$ref` including recursive ones, and `allOf` — whose branches compose, with
+stripping disabled inside them because one branch cannot know what a sibling
+declares.
+
+Member schemas **compose the way JSON Schema says they do**: a member covered
+by `properties` *and* by one or more matching `patternProperties` is
+normalized by every one of them, in that order, and `additionalProperties`
+applies only to a member nothing else covered. A materialized `default` runs
+through its own property's normalizer too, so a defaulted `{ port: '8080' }`
+is shaped exactly like a supplied one rather than keeping its string.
+
+Not walked: `anyOf`, `oneOf`, `if`/`then`/`else`, `not`. Which branch applies
+is only known after validating, and normalizing under one branch can change
+which branch validates — so guessing would be worse than declining. There is
+also no transform hook: an arbitrary transform is application code, not
+schema semantics, and belongs on your side of the boundary.
+
+### The coercion table
+
+Coercion exists to decode transport encodings — query strings, form fields,
+environment variables, CSV cells — where everything arrives as a string. It
+is conservative on purpose: a value it cannot convert unambiguously is passed
+through unchanged, so validation reports the type error instead of the
+normalizer hiding it.
+
+| Declared `type` | Converted | Left alone |
+|---|---|---|
+| `number` | a string that is exactly a JSON number (`'1e5'`, `'-0.5'`) | `'0x10'`, `'1_000'`, `''`, `'Infinity'` |
+| `integer` | as `number`, when the result is integral | `'4.5'` |
+| `boolean` | `'true'`, `'false'` | `'yes'`, `'1'`, `0` |
+| `string` | finite numbers and booleans | objects, arrays, `null` |
+| `null` | `'null'` | `''`, `0`, `false` |
+
+A union `type` (`['string', 'number']`) gives no single target, so coercion is
+skipped rather than guessed. Trimming runs before coercion, so `'  42  '`
+decodes for an integer field.
+
+## Error messages & i18n
+
+Every collected error carries a stable message key (`msgid`) and raw
+structured `params` next to its rendered `message` — prose is produced at
+report time from a **catalog** (a plain object of closures), never on the
+validation hot path. The normative spec is
+[ERROR-MESSAGES.md](./docs/ERROR-MESSAGES.md).
+
+### The `errorMessage` keyword
+
+Author-supplied messages that override *text*, never structure (no error
+aggregation or removal — the deliberate divergence from ajv-errors, whose
+two official plugins are mutually incompatible). Registered at schema
+compile time, resolved only over the failed set at report time — zero
+validation-time cost.
+
+```javascript
+// string form: covers the node AND its subtree (quiet oneOf noise)
+{ "type": "string", "minLength": 8, "errorMessage": "Use at least 8 characters" }
+
+// map form: per failing keyword, '_' as the node catch-all
+{ "type": "integer", "minimum": 18,
+  "errorMessage": { "minimum": "Must be an adult", "_": "Invalid age" } }
+
+// required: per missing property
+{ "required": ["vatId", "name"],
+  "errorMessage": { "required": { "vatId": "VAT id is required for business accounts" } } }
+
+// $query: EBV-false default and per runtime code
+{ "$query": { "$le": ["$.start", "$.end"] },
+  "errorMessage": { "$query": {
+    "default": "start must not be after end",
+    "JQ2003": "start/end must be single values" } } }
+```
+
+Templates interpolate params: `"errorMessage": "needs {limit} characters"`.
+
+### `$msgid` — translatable authored messages
+
+An `errorMessage` (or forms `x-form.message`) may be a **MessageSpec**
+object pointing into the catalog space instead of inline text — that keeps
+schema-authored messages translatable:
+
+```javascript
+{ "type": "number",
+  "errorMessage": { "type": {
+    "$msgid": "checkout.total-invalid",       // catalog key
+    "message": "Total must be a number"       // fallback when no catalog covers it
+  } } }
+```
+
+### Locale packs
+
+```javascript
+import { JarenValidator, compileMessageCatalog, localizeErrors } from '@jarenjs/validate';
+import { nl } from '@jarenjs/locales';
+
+const catalog = compileMessageCatalog(nl);
+const validator = new JarenValidator({ collectErrors: true });
+const validate = validator.compile({ type: 'string', minLength: 2 });
+
+const result = validate('x');                 // English messages
+localizeErrors(result.errors, catalog);       // Dutch, re-rendered from msgid + params
+// 'mag niet minder dan 2 tekens bevatten'
+```
+
+The locale is chosen at **report time**; switching locale never recompiles
+anything. Catalog entries are plain functions, so packs use the platform's
+`Intl.PluralRules`/`Intl.NumberFormat` — see
+[`@jarenjs/locales`](../locales/README.md) for the pack-authoring guide.
+
+### `messages: false`
+
+For applications that render exclusively through `localizeErrors` (or
+their own resolver), skip English rendering entirely:
+
+```javascript
+const validator = new JarenValidator({ collectErrors: true, messages: false });
+// errors arrive with message: '', params and msgid still set
+```
 
 ## Development
 
 Unit tests live in `test/validate/` at the repository root (`npm run test:validate`). Performance against Ajv is measured over the official test suite with the [benchmark workspace](../../benchmark/README.md) (`node benchmark/profiler.js --profile-all`), which also houses the test-failure debugger, coverage and call-graph tools.
 
-This package's internals — the four-phase compile pipeline, ref flattening, annotation tracking, dynamic scope — are described in its own [ARCHITECTURE](./ARCHITECTURE.md) document. For practical usage recipes (options, lightweight setups, custom formats, pitfalls) see the repository [HOWTO](../../HOWTO.md); for the monorepo picture see the repository [README](../../README.md) and [ARCHITECTURE](../../ARCHITECTURE.md); for what is planned next see the [ROADMAP](../../ROADMAP.md).
+This package's internals — the four-phase compile pipeline, ref flattening, annotation tracking, dynamic scope — are described in its own [ARCHITECTURE](./ARCHITECTURE.md) document. For practical usage recipes (options, lightweight setups, custom formats, pitfalls) see the repository [HOWTO](../../docs/HOWTO.md); for the monorepo picture see the repository [README](../../README.md) and [ARCHITECTURE](../../docs/ARCHITECTURE.md); for what is planned next see the [ROADMAP](../../docs/ROADMAP.md).