ata-validator 1.21.0 → 1.22.1

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to ata-validator are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project adheres to semantic versioning.
 
+## 1.22.1 - 2026-09-16
+
+### Fixed
+
+- `validateJSON()` did not return on a document that ends inside an array. `validateJSON('[')` was one byte, any schema, the default configuration, and it never came back. On a rejection the error carries a caret, so a map from pointer to position is built from the raw text; its array loop asked for the next element without checking that the input had ended, `walk` returned without moving, and nothing else could close the array. `'[}'` hung the same way, because a character that begins no value leaves the position where it was. The object loop escaped only by accident: an unterminated string throws, and `lib/data-position-cache.js` catches throws. It cannot catch a loop. Both container loops now stop at the end of the input, and the array loop stops when an iteration does not advance, so a truncated document still yields a map of what was there.
+  - A regression here is an infinite loop, which an ordinary test cannot report because it never reaches a failure. `tests/test_malformed_json_termination.js` runs its corpus in a child process under a watchdog, so a hang becomes a timeout and a red test. The corpus is every prefix of ten documents plus characters inserted where they cannot begin a value: 1793 inputs, 7172 verdicts. It was confirmed to fail before this change and pass after.
+  - `tests/fuzz_positions.js` had never fed malformed text to this walker; it fuzzes schema positions with `JSON.stringify` output, which is always well formed. Nothing else changes: on the same five-field schema, `validate()` on a valid document, `validate()` on an invalid one with the errors read, and `validateJSON()` on both are all within measurement noise of 1.22.0.
+
+- `unevaluatedProperties: false` reported the boolean schema underneath the keyword instead of the keyword itself: `keyword: 'not'`, empty `params`, and an `instancePath` pointing at the offending member rather than the object holding it. Nothing in that error said which key was unexpected, so a caller branching on `params.unevaluatedProperty` to flag unknown keys saw nothing at all. It now reports `unevaluatedProperties` on the object, with `params.unevaluatedProperty` naming the key, one error per key. `unevaluatedItems: false` had the same shape and now reports one error for the array, with `params.limit` at the first unevaluated position. Both engines were changed together and `tests/test_unevaluated_error_shape.js` holds them to it. Reported by a config linter reading `err.params.unevaluatedProperty` through `ata-validator/compat`.
+- `verbose: true` attached only `parentSchema`. It now also attaches `data`, the value the error points at, and `schema`, the failing keyword's own value, which is the whole set the option is supposed to carry. Without `data` a caller had to walk the document by the instance path itself. The default error shape is unchanged: the two fields appear only when `verbose` is on, including on the errors `ata-validator/compat` synthesises for an `if` wrapper.
+
+### Changed
+
+- `additionalProperties: false` no longer compiles to a comparison per declared name. It was one comparison per name per key of the document, which is quadratic in the number of properties: a 1000-property schema spent 75 µs on a document where the same schema without the keyword took 3, and doubling the properties quadrupled that. Above 128 declared names the generated code now reads a name lookup built once per compiled function; below that the comparison chain stays, because it allocates nothing and the two are the same within noise there.
+  - Cross-process medians, one variant per process, properties of type string: 250 names 8.76 µs to 5.49, 500 names 26.29 to 12.47. With no per-property work, so the membership test is all that is measured: 1000 names 77.3 µs to 18.1, 2000 names 273.6 to 38.9.
+  - Measured and not taken: `for...in` over the document instead of an indexed loop over `Object.keys` was about a quarter slower at every size, even though it allocates no key array.
+  - `tests/test_additional_properties_scaling.js` guards this structurally, on the emitted source: the lookup is present above the threshold, absent below it, and declared outside the function that runs per call. It asserts no timing, because a wall-clock ratio was not a guard here: the quadratic shape measured 7.7x for four times the properties on the machine the test was written on, where a CI runner measured 8.3x for the fixed code. The comparison chain short-circuits as soon as a key matches, so the ratio never separated the two. Found by a config linter whose schema is generated from a project's environment variables, so its property count is whatever the project has.
+
+## 1.22.0 - 2026-09-14
+
+### Fixed
+
+- A schema validated once with `isValidObject()` lost its generated error function for the rest of the process. The verdict-only fast path compiles that one function and seeds the shared compile cache with the other two set to null, meaning "not built yet"; the full compile read those nulls as "the compiler declined this schema" and never tried again, so errors fell back to the interpreted engine or the addon. Every server hits that order, because most documents are valid. Cache entries now record whether they are complete. Verdicts and error content were never affected, and `tests/test_compile_cache_order.js` runs both orders in separate processes and holds the engine and the error list equal.
+  - Measured on a five-field schema with an enum and a format, after validating one valid document: `validate(bad).errors` 3.89 µs to 0.66 µs, the Standard Schema path 3.52 µs to 0.07 µs. With no addon installed at all (`ATA_NO_NATIVE=1`), where the fallback was the interpreter rather than the addon, 1.05 µs to 0.66 µs and 0.42 µs to 0.07 µs.
+  - `engine()` reported `closure` for a schema that compiles, once a valid document had been validated first. It now reports `codegen` in either order.
+
+### Changed
+
+- The official test suite submodule moved 60 commits forward, to 2026-09-13. All three dialects stay at zero regressions and the case counts rose: Draft 2020-12 1299 to 1301, draft 7 927 to 929, the v1 dialect 1133 to 1135, identical with code generation blocked. The buffer path agrees with `validate()` on all 3365 of them. Every figure in the README, the docs and the contributor notes was remeasured and updated together, and the floors in `tests/test_no_eval.js` were raised so the new cases cannot be lost silently.
+
+- `uri` is one walk over the string instead of three, and reads its character classes out of tables instead of comparison chains. It was the most expensive thing an ordinary document carried: on a schema with five formats over a 1.6 KB payload, format assertion was 94 percent of the validation cost and `uri` was most of that, while the structural check of the whole nested document was 43 ns. The authority's landmarks, the last `@`, the colons after it and whether a bracket came before it, are now recorded during the character scan rather than by cutting the authority out with `slice` and asking the copy for `lastIndexOf` and two regular expressions.
+  - `format: uri` on one string, through a compiled validator: 92 to 42 ns. The same product schema's document: 697 to 423 ns. End to end, where `JSON.parse` is the other 75 percent: 2.98 to 2.69 µs.
+  - Measured, and not taken: nine `===` tests per character cost more than the loop they guarded, a lookup table is 2.3x that chain, and a three-regex formulation of the whole rule landed at 65 ns against the table walk's 41.
+  - The code generator hoists the walk once per compiled function and calls it, rather than inlining it at each call site where the tables would have to be rebuilt. This is the shape `email` already had. `tests/test_uri_helper_parity.js` holds the function, the generated text and a compiled validator to the same answer over 35,677 strings built from the walk's own boundaries.
+
+- Enriching a rejection no longer reads more of the document than the diagnostic it produces. `received` describes the offending value in at most 60 characters, and it used to find out whether a value fitted by serialising it whole, so a `required` error on a large payload cost a `JSON.stringify` of that payload, once per error. Sizing is now bounded by those 60 characters and stops as soon as they are spent. Enriching one error on a document holding a thousand rows: 61.5 µs to 160 ns, and flat in the size of the document rather than linear. On the schema-benchmarks product schema, where `validate()` reports 16 errors, reading `.errors` went from 9.84 to 5.10 µs (48 percent less) on the same machine, separate processes. Verdict paths, `isValidObject()` and the Standard Schema bridge are unchanged.
+- An object too large to show reports its shape rather than its serialised size: `[object, 5 keys]` where it used to say `[object, ~0.1KB]`. This is the only change to error output; every value that printed its body before prints the same body now, including nested objects, arrays and values with their own `toJSON`.
+- The error's value is resolved from its pointer once and handed to both the `received` repr and the suggestion sources. `lib/suggestions.js` had a second pointer walk that split the string and mapped over the segments; both paths now use `resolvePointer` in `lib/pointer.js`.
+- A `required` typo hint is offered on containers of up to 64 keys. Past that the nearest key stops being evidence of a typo, which is the cap `suggestEnumTypo` already applied to its candidate list, and the scan is a distance computation per key.
+- `levenshtein` reads characters by code and swaps its two rows through a temporary. The destructured swap it used built an array per row. About 9 percent faster on the key pairs the suggestion sources compare.
+- `tests/test_enrich_received.js` holds enrichment to within 4x across a hundredfold increase in document volume. Before this change the same measurement was 122x.
+
 ## 1.17.2 - 2026-09-13
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # ata-validator
 
-JSON Schema validation with first-class TypeScript and zero runtime cost. AOT compile your schemas to per-schema ESM modules with no validator dependency. `Validator<T>` composes with TypeBox, Zod-from-JSON-Schema, Valibot, or hand-written types. Runtime API available for dynamic schemas. Draft 2020-12, draft 7 and the [JSON Schema v1 dialect](#dialects).
+JSON Schema validation that compiles for speed and still runs where code generation is blocked. The compiled and interpreted engines answer identically, at 100% of the official suite in both modes, across Draft 2020-12, draft 7 and the [JSON Schema v1 dialect](#dialects). First-class TypeScript inference, and `ata build` emits a standalone module that imports nothing.
 
 [![npm](https://img.shields.io/npm/v/ata-validator)](https://www.npmjs.com/package/ata-validator)
 [![License](https://img.shields.io/npm/l/ata-validator)](LICENSE)
@@ -20,11 +20,11 @@ The `ata-validator` package itself is pure JavaScript. The native accelerator (s
 npm install ata-validator --omit=optional
 ```
 
-or set `ATA_NO_NATIVE=1` at runtime. Typical schemas compile to specialized JS; shapes the compiler cannot represent (some `$dynamicRef`, cyclic `$ref`, unusual keyword interactions) fall back to an interpreted engine, so every schema validates in every environment. The pure-JS setup scores the same on the official suite as the native one, 1299 of 1299 Draft 2020-12 cases. Only the buffer and parallel APIs (`isValid` on raw buffers, `countValid`, `batchIsValid`, `validateAndParse`) need the native engine and say so with a clear error.
+or set `ATA_NO_NATIVE=1` at runtime. Typical schemas compile to specialized JS; shapes the compiler cannot represent (some `$dynamicRef`, cyclic `$ref`, unusual keyword interactions) fall back to an interpreted engine, so every schema validates in every environment. The pure-JS setup scores the same on the official suite as the native one, 1301 of 1301 Draft 2020-12 cases. Only the buffer and parallel APIs (`isValid` on raw buffers, `countValid`, `batchIsValid`, `validateAndParse`) need the native engine and say so with a clear error.
 
-Those four now agree with `validate()` on every case of the official suite, 3359 across three dialects. The native walker behind them does not handle every shape (`contains`, `unevaluatedProperties`, `patternProperties`, tuple `items`, cross-document `$ref`, a few formats), so for schemas using one of those the buffer APIs parse the bytes and answer through `validate()`; the list is in `lib/buffer-gate.js`. Typical request schemas stay on the zero-copy path. `npm test` holds the disagreement count at zero.
+Those four now agree with `validate()` on every case of the official suite, 3365 across three dialects. The native walker behind them does not handle every shape (`contains`, `unevaluatedProperties`, `patternProperties`, tuple `items`, cross-document `$ref`, a few formats), so for schemas using one of those the buffer APIs parse the bytes and answer through `validate()`; the list is in `lib/buffer-gate.js`. Typical request schemas stay on the zero-copy path. `npm test` holds the disagreement count at zero.
 
-Where `new Function` is refused altogether, on Cloudflare Workers, Deno Deploy or under a strict Content-Security-Policy, ata drops to the interpreted engine and scores the same 1299 of 1299 with code generation blocked. No flags, and on Workers no `nodejs_compat` either. See [docs/edge-runtimes.md](docs/edge-runtimes.md).
+Where `new Function` is refused altogether, on Cloudflare Workers, Deno Deploy or under a strict Content-Security-Policy, ata drops to the interpreted engine and scores the same 1301 of 1301 with code generation blocked. No flags, and on Workers no `nodejs_compat` either. See [docs/edge-runtimes.md](docs/edge-runtimes.md).
 
 Node has a switch for exactly that environment, so this takes thirty seconds to check for yourself, on ata or on whatever you use today:
 
@@ -97,6 +97,55 @@ run on the interpreted engine. That engine compiles each schema into a tree of c
 on a six-field object schema a passing payload costs about 136 ns against 8 ns for the same
 shape on the compiled path, both measured warm in one run on the same machine.
 
+## Schemas and models
+
+If you ask a model for structured output and validate the result, the schema is
+part of the prompt and the validation error is part of the retry. Two functions
+produce those strings.
+
+```js
+import { describeSchema, toRetryMessage, Validator } from 'ata-validator'
+
+describeSchema(schema)
+// output: object
+//   status: one of "AWAITING_CLEARANCE", "PART_SETTLED", "CLOSED_OUT"
+//   region_code: one of "R11", "R24", "R37", "R52"
+//   amount: integer, at least 1
+//   no other fields
+
+const r = new Validator(schema).validate(fromTheModel)
+if (!r.valid) toRetryMessage(r.errors)
+// /status: expected one of ["AWAITING_CLEARANCE", "PART_SETTLED", "CLOSED_OUT"], found "partial"
+// /region_code: expected one of ["R11", "R24", "R37", "R52"], found "HH"
+// /amount: expected ≥1, found 0
+// /: unknown property "extra"
+```
+
+Whether this is worth anything depends on the schema, and the measurement that
+says so is
+[public](https://github.com/mertcanaltin/retry-message-experiment), with the
+harness and the raw results.
+
+On constraints a model can work out from the document, a pattern, a date format,
+a currency in uppercase, it changes nothing: 40 of 40 documents recovered on one
+retry with the conventional error text, and 40 of 40 with the detailed one.
+
+On constraints it cannot work out, an `enum` of internal codes while the
+document says "paid in part" and "Hamburg office", the conventional text
+recovered 0 of 30 and the detailed text 30 of 30. The model does not give up
+when it is not told the values, it invents plausible ones, so no number of
+retries closes it.
+
+Stating the constraints up front does the same job earlier. Across four prompts
+on the same fixtures, first attempts that validate: nothing 0 of 30, a lean
+field list 0 of 30, a careful hand-written description 30 of 30 on the inferable
+fixture and 0 of 30 on the opaque one, and `describeSchema` 30 and 23. A person
+writing prose matches the generated description wherever prose works. It is the
+enumerated values a person leaves out.
+
+One model, Claude Haiku 4.5, one schema shape, 30 to 40 documents per arm, no
+temperature control. Read it as a finding, not a law.
+
 ## Error messages
 
 ata's error output is compiler-grade: each error carries a stable code, an inline source frame pointing at the schema file, and another pointing at the offending bytes in the request payload. Renderers ship in three styles:
@@ -153,6 +202,33 @@ Schemas without an `errorMessage` keyword pay nothing: the override pass is only
 
 For consumers who built log dashboards on the v0.14 error shape, `new Validator(schema, { richErrors: false })` returns the legacy shape exactly. For high-throughput paths, `abortEarly: true` continues to short-circuit; the returned error carries `code: 'ATA9000'` and no enrichment.
 
+## Which path, and where
+
+There are two ways to run ata and they suit different places. Measuring the wrong one
+is the most common way to get a misleading number out of this library.
+
+| | compiled with `ata build` | runtime `new Validator(schema)` |
+|---|---|---|
+| In a bundle, gzipped | **1.9 KB** | 75.6 KB |
+| Time to a served request | **3.5 ms** | 10.7 ms |
+| Schema known when | build time | any time |
+
+The bundle row is a ten-field user schema built with
+`bun build --minify --target=browser`. The startup row is a Hono route on Bun 1.4, best
+of seven, against 3.6 ms for the same app doing no validation at all, so the compiled
+path costs nothing measurable to start. The runtime
+figure is what it is because a schema that arrives at run time can use any keyword, so
+the whole engine has to be there. The compiled module imports nothing and contains only
+the checks your schema asks for.
+
+**On a server, use whichever fits your schemas.** 76 KB of JavaScript on a Node or Bun
+process is not a cost anyone notices, and the runtime API is the simpler thing to reach
+for. Speed is the same either way once warm.
+
+**In a browser, on an edge runtime, or anywhere cold starts are charged, compile.** This
+is where the difference is the whole story, and it is also where `new Function` is often
+blocked outright, which the compiled module does not need.
+
 ## When to use the runtime API instead
 
 `ata build` is for schemas you know at build time. If your schemas are user-supplied at runtime (form builders, no-code platforms, dynamic API ingestion), use the runtime API:
@@ -374,7 +450,7 @@ const v = new Validator(schema, {
 
 ### Build-time compile (`ata compile`)
 
-The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. Typical output is ~1 KB gzipped compared to ~65 KB for the full runtime bundled for the browser.
+The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. Typical output is about 2 KB gzipped for a ten-field schema, against 74 KB for the runtime bundled for the browser.
 
 ```bash
 npx ata compile schemas/user.json -o src/generated/user.validator.mjs
@@ -404,7 +480,7 @@ CLI options:
 | `-o, --output <file>` | `<schema>.validator.mjs` | Output path |
 | `-f, --format <fmt>` | `esm` | `esm` or `cjs` |
 | `--name <TypeName>` | from filename | Root type name in the `.d.ts` |
-| `--abort-early` | off | Generate the stub-error variant (~0.5 KB gzipped) |
+| `--abort-early` | off | Generate the stub-error variant, about a third of the source |
 | `--no-types` | off | Skip the `.d.mts` / `.d.cts` output |
 
 For a project with many schemas, `ata build <glob>` compiles them all in one command:
@@ -415,13 +491,19 @@ npx ata build 'schemas/*.json' --out-dir build/validators --check
 
 Run with `--watch` during development for incremental rebuilds.
 
-Typical bundle sizes (10-field user schema, gzipped):
+Bundle sizes for a 10-field user schema, minified and gzipped, measured with
+`bun build --minify --target=browser`:
 
-| Variant | Size | Notes |
+| What the app imports | Size | Notes |
 |---|---|---|
-| `ata-validator` runtime | ~27 KB | Full compiler + all keywords |
-| `ata compile` (standard) | **~1.1 KB** | Validator + detailed error collector |
-| `ata compile --abort-early` | **~0.5 KB** | Validator + stub errors only |
+| `Validator` from `ata-validator` | 74.1 KB | The compiler ships with it, because a runtime schema can use any keyword |
+| `isValid` from the compiled module | **1.9 KB** | Nothing else is reachable, so the error collector is dropped |
+| `validate` from the compiled module | **3.6 KB** | Adds the detailed error collector |
+
+`--abort-early` makes the generated source about three times smaller, and after
+bundling it makes no difference: importing only `isValid` already leaves the error
+collector unreachable, and a bundler drops it. Use the flag to cut the file on disk,
+not to cut what ships.
 
 Programmatic API if you prefer to script it:
 
@@ -560,7 +642,7 @@ Both are implemented in the interpreted engine, so a v1 schema that uses `$dynam
 
 ### Known limitations
 
-Running the whole Draft 2020-12 suite with nothing excluded, `format` and `default` under specification semantics (`assertFormat: false`, `useDefaults: false`), gives 1299 of 1299 cases. Draft 7 gives 927 of 927. The v1 dialect gives 1133 of 1133. `npm run test:suite` reproduces all three.
+Running the whole Draft 2020-12 suite with nothing excluded, `format` and `default` under specification semantics (`assertFormat: false`, `useDefaults: false`), gives 1301 of 1301 cases. Draft 7 gives 929 of 929. The v1 dialect gives 1135 of 1135. `npm run test:suite` reproduces all three.
 
 Areas that remain deliberate scope decisions for 1.x:
 

package/compat.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { resolvePointer } = require('./lib/pointer.js');
+
 // Drop-in for the default validator's class. `const Ajv = require('ata-validator/compat')`
 // and the rest of the file stays as it was: `new Ajv(opts)`, `compile`,
 // `validate`, `addSchema`, `getSchema`, `removeSchema`, `addFormat`,
@@ -174,7 +176,16 @@ class Ata {
         validate.errors = null;
         return true;
       }
-      const errors = shaper === null ? result.errors : shaper(result.errors, data);
+      let errors = shaper === null ? result.errors : shaper(result.errors, data);
+      // Errors the shaper synthesises, the `if` wrapper among them, are built
+      // from the group rather than carried up from the validator, so verbose
+      // mode has to fill in the value they point at here or they would be the
+      // only ones missing it.
+      if (this.opts.verbose) {
+        errors = errors.map((e) => (e && !('data' in e)
+          ? { ...e, data: resolvePointer(data, e.instancePath || '', undefined) }
+          : e));
+      }
       validate.errors = shaper === null && !allErrors ? errors.slice(0, 1) : errors;
       return false;
     };

package/index.d.ts

@@ -72,6 +72,37 @@ export function renderPretty(errors: RichValidationError[], opts?: PrettyOptions
 export function renderCompact(errors: RichValidationError[], opts?: CompactOptions): string;
 export function renderJSON(errors: RichValidationError[], opts?: JSONRenderOptions): string;
 
+/** Options for {@link describeSchema}. */
+export interface DescribeSchemaOptions {
+  /** What to call the top level in the description. Defaults to `output`. */
+  name?: string;
+}
+
+/**
+ * The schema's constraints as prose, for the prompt that asks a model to
+ * produce a document. Values a model cannot infer, an `enum` of internal codes
+ * most of all, are the ones worth stating: measured on one fixture, naming them
+ * took first-attempt validity from 0 of 30 to 23 of 30, where a careful
+ * hand-written description scored 0 on exactly those fields.
+ * https://github.com/mertcanaltin/retry-message-experiment
+ */
+export function describeSchema(schema: object, opts?: DescribeSchemaOptions): string;
+
+/** Options for {@link toRetryMessage}. */
+export interface RetryMessageOptions {
+  /** Most errors to include. Defaults to 20, because a model does not act on a long list. */
+  limit?: number;
+}
+
+/**
+ * The errors as a string to send back to a model, naming what was expected and
+ * what arrived. On constraints a model can infer from context this changes
+ * nothing; where a constraint is an internal vocabulary it was the difference
+ * between 0 of 30 and 30 of 30 recovered on one retry.
+ * https://github.com/mertcanaltin/retry-message-experiment
+ */
+export function toRetryMessage(errors: RichValidationError[], opts?: RetryMessageOptions): string;
+
 /** A user-supplied format checker. Receives the candidate value, returns true if valid. */
 export type FormatChecker = (value: string) => boolean;
 

package/index.js

@@ -458,13 +458,17 @@ Object.defineProperty(RichRejection.prototype, 'errors', {
       const enrich = this._enrich;
       let raw = this._result.errors || [];
       if (raw.length > 1) raw = sortErrorsBySchemaOrder(this._root, raw);
-      const cached = (enrich && raw.length)
-        ? raw.map((e) => enrich(e, {
+      // One options object for the whole list, not one per error.
+      const opts = enrich && raw.length
+        ? {
             data: this._data,
             positions: this._positions,
             schemaPositions: self._schemaPositions,
             schemaFile: self._source ? self._source.path : undefined,
-          }))
+          }
+        : null;
+      const cached = opts
+        ? raw.map((e) => enrich(e, opts))
         // The v0.14 shape is a fixed key set; the ordering key the
         // generated code carries is dropped from it here.
         : raw.map(stripOrdinal);
@@ -1005,7 +1009,12 @@ class Validator {
     // there.
     if (this._v1Dynamic || this._usesKeywords || !codegenAvailable()) {
       jsFn = null; jsCombinedFn = null; jsErrFn = null;
-    } else if (cached && !_forceNapi) {
+    // `full` separates an entry that holds every compiled function from one
+    // the verdict-only fast path seeded, where `combined` and `errFn` are null
+    // because nothing has tried to build them yet. Both halves of that
+    // distinction are null, and reading the second as the first costs this
+    // schema its generated error function for the life of the process.
+    } else if (cached && cached.full && !_forceNapi) {
       jsFn = cached.jsFn;
       jsCombinedFn = cached.combined;
       jsErrFn = cached.errFn;
@@ -1019,13 +1028,13 @@ class Validator {
       _isCodegen = !!_cgFn;
       this._engine = _cgFn ? 'codegen' : jsFn ? 'closure' : null;
       if (!uf) {
-        _compileCache.set(mapKey, { jsFn, combined: jsCombinedFn, errFn: jsErrFn, isCodegen: _isCodegen });
+        _compileCache.set(mapKey, { jsFn, combined: jsCombinedFn, errFn: jsErrFn, isCodegen: _isCodegen, full: true });
       }
     } else {
       jsFn = null; jsCombinedFn = null; jsErrFn = null;
     }
     this._jsFn = jsFn;
-    if (this._engine === undefined) this._engine = cached ? (cached.isCodegen ? 'codegen' : jsFn ? 'closure' : null) : null;
+    if (this._engine === undefined) this._engine = (cached && cached.full) ? (cached.isCodegen ? 'codegen' : jsFn ? 'closure' : null) : null;
 
     // Data mutators -- try codegen first (12x faster), fallback to closure arrays.
     // Follow cross-refs so coercion/defaults/removeAdditional see the referenced
@@ -1224,19 +1233,36 @@ class Validator {
               }
             : (data) => (jsFn(data) ? VALID_RESULT : errFn(data));
       }
-      // Verbose mode: populate parentSchema on each error.
-      // Errors may be frozen, so clone them with the extra field.
+      // Verbose mode: populate parentSchema, schema and data on each error, the
+      // three fields the default error shape carries under the same option.
+      // `data` is the value the error points at; without it a caller has to
+      // walk the document by the instance path itself, which is what one
+      // migration ended up writing by hand. Errors may be frozen, so clone
+      // them with the extra fields.
       if (this._verbose) {
         const inner = this.validate;
         const root = this._schemaObj;
+        const { resolvePointer } = require('./lib/pointer.js');
         this.validate = (data) => {
           const result = inner(data);
           if (result && !result.valid && result.errors) {
-            const enriched = result.errors.map((err) =>
-              err && err.parentSchema === undefined
-                ? { ...err, parentSchema: resolveSchemaByPath(root, err.schemaPath) }
-                : err
-            );
+            const enriched = result.errors.map((err) => {
+              if (!err || err.parentSchema !== undefined) return err;
+              const parentSchema = resolveSchemaByPath(root, err.schemaPath);
+              // The last segment of the schema path is the keyword that
+              // failed, so its value on the parent is that keyword's schema.
+              const sp = typeof err.schemaPath === 'string' ? err.schemaPath : '';
+              const last = sp.slice(sp.lastIndexOf('/') + 1).replace(/~1/g, '/').replace(/~0/g, '~');
+              const keywordSchema = (parentSchema !== null && typeof parentSchema === 'object' && last)
+                ? parentSchema[last]
+                : undefined;
+              return {
+                ...err,
+                parentSchema,
+                schema: keywordSchema,
+                data: resolvePointer(data, err.instancePath, undefined),
+              };
+            });
             return { valid: false, errors: enriched };
           }
           return result;
@@ -1549,12 +1575,13 @@ class Validator {
               // Declaration order, as validate() applies it; the text path
               // used to enrich in emission order.
               const ordered = result.errors.length > 1 ? sortErrorsBySchemaOrder(this._schemaObj, result.errors) : result.errors;
-              const enriched = ordered.map((e) => enrich(e, {
+              const enrichOpts = {
                 data: parsedData,
                 positions,
                 schemaPositions: this._schemaPositions,
                 schemaFile: this._source ? this._source.path : undefined,
-              }));
+              };
+              const enriched = ordered.map((e) => enrich(e, enrichOpts));
               if (enriched.length > 1) attachRelated(enriched);
               attachDiagnosticSource(enriched, {
                 data: parsedData,
@@ -1776,9 +1803,11 @@ class Validator {
     this._jsFn = jsFn;
     if (jsFn) {
       this.isValidObject = jsFn;
-      // seed cache with codegen, combined/errFn filled later by _ensureCompiled
+      // A partial entry: the verdict function is real, the other two are not
+      // built yet rather than declined. `full: false` says so, so the next
+      // caller that needs errors compiles them instead of inheriting nulls.
       if (!uf) {
-        if (!cached) _compileCache.set(mapKey, { jsFn, combined: null, errFn: null });
+        if (!cached) _compileCache.set(mapKey, { jsFn, combined: null, errFn: null, full: false });
         else cached.jsFn = jsFn;
       }
     }

package/lib/data-positions.js

@@ -63,6 +63,10 @@ function buildDataPositionMap (input) {
       i++;
       while (true) {
         skipWs();
+        // The input is not required to be valid JSON: this map is built to
+        // put a caret on a syntax error, so a document that stops in the
+        // middle of a container is the normal case, not an impossible one.
+        if (i >= n) break;
         if (text.charCodeAt(i) === 0x7d) { i++; break; }
         if (text.charCodeAt(i) === 0x2c) { i++; continue; }
         skipWs();
@@ -88,9 +92,15 @@ function buildDataPositionMap (input) {
       let idx = 0;
       while (true) {
         skipWs();
+        if (i >= n) break;
         if (text.charCodeAt(i) === 0x5d) { i++; break; }
         if (text.charCodeAt(i) === 0x2c) { i++; continue; }
+        const before = i;
         walk(path.concat([String(idx)]));
+        // A character that begins no value at all, a stray `}` for instance,
+        // leaves the position where it was, and a loop that does not advance
+        // does not end. `validateJSON('[')` hung here on one byte.
+        if (i === before) break;
         idx++;
       }
     } else if (ch === 0x22) {

package/lib/enrich-error.js

@@ -2,9 +2,70 @@
 
 const { CODES, codeFor, fromNative } = require('./error-codes');
 const { suggestFor } = require('./suggestions');
+const { resolvePointer } = require('./pointer');
+
+// A pointer that walked out of the document: no value to report, not even the
+// word 'undefined', which is what an absent key reports.
+const MISSING = Symbol('ata.received.missing');
 
 const DOC_BASE = 'https://ata-validator.com/e/';
 
+// The number of characters JSON.stringify would emit for `v`, or -1 as soon as
+// that passes `budget` or the value holds something a plain walk cannot size.
+// The point is the bound: `reprValue` only ever shows a body of 60 characters,
+// so sizing one never needs to read further than that, and a `required` error
+// on a large document used to serialise the whole container to find out it was
+// too big. Keys are counted unescaped, which makes the result a lower bound,
+// and the caller rechecks the real length on the string it ends up building.
+function jsonSizeWithin (v, budget) {
+  if (budget < 0) return -1;
+  if (v === null) return 4;
+  const t = typeof v;
+  if (t === 'number') return Number.isFinite(v) ? String(v).length : 4;
+  if (t === 'boolean') return v ? 4 : 5;
+  if (t === 'string') return v.length + 2 > budget ? -1 : v.length + 2;
+  if (t !== 'object') return -1;
+  // A value with its own toJSON serialises to something only that method can
+  // say. Sizing it exactly would mean running it, and a Date's toJSON alone
+  // costs more than serialising the object around it, so this returns the
+  // smallest thing it could produce. Undershooting is safe: the caller only
+  // uses the estimate to decide whether to try, and rechecks the real length.
+  if (typeof v.toJSON === 'function') return 2;
+  if (Array.isArray(v)) {
+    let n = 2;
+    for (let i = 0; i < v.length; i++) {
+      n += i === 0 ? 0 : 1;
+      if (n > budget) return -1;
+      const c = jsonSizeWithin(v[i], budget - n);
+      if (c < 0) return -1;
+      n += c;
+      if (n > budget) return -1;
+    }
+    return n;
+  }
+  const proto = Object.getPrototypeOf(v);
+  if (proto !== Object.prototype && proto !== null) return -1;
+  let n = 2;
+  let first = true;
+  // for-in rather than Object.keys: the prototype is checked above, so there
+  // is nothing inherited to enumerate, and this walk runs per error.
+  for (const k in v) {
+    const val = v[k];
+    // Keys JSON drops cost nothing, but they also cost nothing to skip.
+    if (val === undefined || typeof val === 'function' || typeof val === 'symbol') continue;
+    // Charge the key before reading the value, so a budget already spent
+    // returns without descending into it.
+    n += k.length + 3 + (first ? 0 : 1);
+    if (n > budget) return -1;
+    first = false;
+    const c = jsonSizeWithin(val, budget - n);
+    if (c < 0) return -1;
+    n += c;
+    if (n > budget) return -1;
+  }
+  return n;
+}
+
 function reprValue (v) {
   if (v === undefined) return 'undefined';
   if (v === null) return 'null';
@@ -16,13 +77,21 @@ function reprValue (v) {
   if (t === 'number' || t === 'boolean') return String(v);
   if (Array.isArray(v)) return `[array, ${v.length} items]`;
   if (t === 'object') {
+    if (jsonSizeWithin(v, 60) >= 0) {
+      try {
+        const s = JSON.stringify(v);
+        if (s !== undefined && s.length <= 60) return s;
+      } catch {
+        return '[object, unserializable]';
+      }
+    }
+    let n;
     try {
-      const s = JSON.stringify(v);
-      if (s.length <= 60) return s;
-      return `[object, ~${(s.length / 1024).toFixed(1)}KB]`;
+      n = Object.keys(v).length;
     } catch {
       return '[object, unserializable]';
     }
+    return `[object, ${n} ${n === 1 ? 'key' : 'keys'}]`;
   }
   return `[${t}]`;
 }
@@ -45,28 +114,14 @@ function expectedFor (err) {
   }
 }
 
-function pickReceived (err, data) {
-  if (!data && data !== 0 && data !== false) return undefined;
-  // Walk JSON pointer to extract the actual offending value. This runs for
-  // every error on every rejected payload, so the walk reads segments straight
-  // out of the pointer: no leading-slash regex, no parts array, and no unescape
-  // pass on the segments that carry no `~`.
+// The value the error's pointer resolves to, or MISSING when the pointer walks
+// out of the document. Resolved once per error and handed to both the
+// `received` repr and the suggestion sources, which used to walk it each.
+function resolveAt (err, data) {
+  if (!data && data !== 0 && data !== false) return MISSING;
   const p = err.instancePath || err.path || '';
-  if (!p) return reprValue(data);
-  const len = p.length;
-  let cur = data;
-  let i = p.charCodeAt(0) === 47 ? 1 : 0; // 47 is '/'
-  for (;;) {
-    let j = p.indexOf('/', i);
-    if (j === -1) j = len;
-    let seg = p.slice(i, j);
-    if (seg.indexOf('~') !== -1) seg = seg.replace(/~1/g, '/').replace(/~0/g, '~');
-    if (cur == null) return undefined;
-    cur = cur[seg];
-    if (j === len) break;
-    i = j + 1;
-  }
-  return reprValue(cur);
+  if (!p) return data;
+  return resolvePointer(data, p, MISSING);
 }
 
 /**
@@ -146,13 +201,15 @@ function enrich (rawErr, opts) {
   const meta = CODES[code];
   const path = rawErr.instancePath != null ? rawErr.instancePath : (rawErr.path || '');
 
+  const at = data !== undefined ? resolveAt(rawErr, data) : MISSING;
+
   const out = {
     code,
     message: rawErr.message || (meta && meta.headline) || 'validation failed',
     keyword,
     path,
     expected: expectedFor(rawErr),
-    received: data !== undefined ? pickReceived(rawErr, data) : undefined,
+    received: at === MISSING ? undefined : reprValue(at),
     schemaPath: rawErr.schemaPath,
     docUrl: DOC_BASE + code,
     // Back-compat aliases (additive, present in both rich and legacy paths)
@@ -162,6 +219,12 @@ function enrich (rawErr, opts) {
     parentSchema: rawErr.parentSchema,
   };
 
+  // Verbose mode's two other fields. Carried only when the raw error has them,
+  // so the default error shape does not grow two undefined keys for everyone
+  // who never asked for verbose.
+  if ('data' in rawErr) out.data = rawErr.data;
+  if ('schema' in rawErr) out.schema = rawErr.schema;
+
   // oneOf/anyOf collapse: preserve the nested branch errors so the pretty
   // renderer can surface the closest variant's diagnostics.
   if (rawErr.branchErrors) out.branchErrors = rawErr.branchErrors;
@@ -187,7 +250,7 @@ function enrich (rawErr, opts) {
   // Suggestion attachment runs last so it can read `received`, `params`, and
   // `keyword` from the enriched shape. `data` is the full input object so the
   // required-typo source can scan sibling keys.
-  const sugg = suggestFor(out, opts && opts.data);
+  const sugg = suggestFor(out, data, at === MISSING ? undefined : at);
   if (sugg) out.suggestion = sugg;
 
   const detail = detailFor(rawErr, out);