ata-validator 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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.9.0 - 2026-08-28
+
+### Errors
+
+- Rendered diagnostics now say where the problem is. Every `renderPretty` and `renderCompact` block carries the JSON path, and a source frame with a caret on the failing token when one can be built faithfully: from the text on the `validateJSON` path, or from the object when the renderer is handed `{ data }`. Object-input frames are reconstructed by re-serializing the value and the output says so once, because the line numbers refer to that reconstruction. No frame is reconstructed under `coerceTypes`, `removeAdditional` or a schema with `default` values, since the object in hand is not what the caller sent; the output names the option instead.
+- Headlines state the observation rather than the rule: `expected integer, found string` in place of `must be integer`. Two `additionalProperties` violations no longer render as identical blocks; the property name is in the headline. A composition failure with a `const` discriminator names it, `no variant matches kind "circle"`, anchors inside the closest branch, and its branch notes read `minimum: expected ≥0, found -1`.
+- A property typed `nmae` where `name` was required renders as one diagnostic with `did you mean "name"?` instead of two. The correlation requires that no other missing or extra key in the same object is equally close; on a tie nothing is merged. Both errors stay in the array and point at each other through the new `related` field, and the footer reads `8 schema violations in input, shown as 7 diagnostics` so the count never drifts from `errors.length`.
+- Diagnostics are ordered by document position, with cause before effect only as a tie-break within one container. Carets are clamped to the line they sit under; a root-level error used to draw one the width of the whole document.
+- Under `richErrors` (the default) errors gain `detail`, `related`, `anchor` and `rank`. Existing fields, array order and array length are unchanged; `richErrors: false` still returns the v0.14 shape. `useDefaults`, on by default, is now documented.
+- Measured on a ten-case corpus scored on four questions per diagnostic (says where, states what was found, distinguishable from its neighbours, offers a way forward): 3 of 60 before, 58 of 58 after, and `tests/test_diagnostics_score.js` holds the floor at 95%. Cost on the reject path when `.errors` is read, master against this change on the same machine: a one-error document 330 to 395 ns, a seven-error document with a typo pair 2.45 to 2.95 µs. `validate().valid` is unchanged at 5 ns. Fastify's own suite through fastify-ata stays at 178 of 184.
+
+## 1.8.2 - 2026-08-28
+
+### Fixed
+
+- A `pattern` of the form `^[class]+$`, `^[class]{m,n}$` or `^[class]{n}$` with n above 16 could be violated without `validate()` saying so. The boolean program compiles those patterns to an inline character loop wrapped in an arrow function, and the rewrite that turns the boolean program into the error-reporting one replaced the `return false` and `return true` inside that arrow with `return E(d)` and `return R`. Both are objects, so the arrow started returning a truthy value on mismatch, the enclosing `!(cond && obj)` went false, and the error program accepted what the boolean program had rejected.
+
+  What that looked like from outside depended on the path. Without preprocessing, `validate()` still rejected, because the boolean verdict runs first, but the error it produced was a generic `schema validation failed` with no keyword, no `params.pattern` and no path. With preprocessing, which means any schema carrying a `default` or a validator built with `coerceTypes` or `removeAdditional`, the error program is installed as `validate()` directly and the result was `valid: true`. `Validator.bundleStandalone` and `bundleCompact` embed the same program and had the same silent accept. `ata compile` output is built from the boolean program and was not affected. The rewrite has been wrong since 0.6.0; the official suite never exercised these pattern shapes, so nothing caught it.
+
+  The rewrite now leaves the body of an arrow function alone, the same way it already left `function` bodies alone. `tests/test_hybrid_agreement.js` compares the rewritten program with the boolean it came from on every affected shape, at the root, in a property, in array items, through `bundleStandalone` and through a compiled module, and checks the two preprocessing cases directly. `tests/test_codegen_entrypoint_agreement.js` now compares the rewritten program as a fifth participant across the whole official suite. `tests/test_ajv_errors.js`, which had been failing on exactly this for as long as the bug existed, is now part of `npm test`.
+
+### Changed
+
+- Ranking an error into schema declaration order no longer re-derives the rank on every error of every failing document. It was splitting the schema path with two regular expressions per segment and then scanning `Object.keys(node)` at each level, which was 8.5% of the error path in a profile, for an answer that depends only on the schema and the path. The rank is now cached per path under its root, each node's keys are indexed once, and escape handling is skipped for segments with no tilde. That function drops from 8.5% to 1.4% of the error path, and the error path as a whole gets 3.5% faster, median of eleven interleaved runs. `docs/performance-notes.md` records the larger gap this was measured against; it is not closed by this change.
+
 ## 1.8.1 - 2026-08-27
 
 ### Changed

package/index.js

@@ -373,12 +373,64 @@ function resolveSchemaByPath(rootSchema, schemaPath) {
 // order AJV emits and what schema authors read top to bottom. Segments that
 // cannot be resolved (cross-schema refs, normalized keys) end the walk; the
 // stable sort then keeps such errors in engine emission order.
+// The rank of a `schemaPath` under a given root is fixed: the schema does not
+// change between validations, so neither does the answer. It was recomputed for
+// every error of every failing document, and computing it is not cheap. Two
+// caches, both keyed on things that do not change:
+//
+//   rootSchema -> schemaPath -> rank, so a path is walked once ever
+//   node       -> key -> its index, so the walk stops calling Object.keys and
+//                        scanning the result for a string
+//
+// A failing route sees the same handful of schemaPaths over and over, which is
+// what makes the first one worth having.
+const _rankCache = new WeakMap();
+const _keyIndexCache = new WeakMap();
+
+function keyIndex(node, seg) {
+  let index = _keyIndexCache.get(node);
+  if (index === undefined) {
+    index = new Map();
+    const keys = Object.keys(node);
+    for (let i = 0; i < keys.length; i++) index.set(keys[i], i);
+    _keyIndexCache.set(node, index);
+  }
+  const at = index.get(seg);
+  return at === undefined ? -1 : at;
+}
+
+// `~1` and `~0` are the only escapes a JSON pointer has, and almost no schema
+// key contains a tilde. Looking for one is far cheaper than two regex passes
+// over every segment of every path.
+function unescapePointerSegment(seg) {
+  return seg.indexOf('~') < 0 ? seg : seg.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
 function schemaOrderRank(rootSchema, schemaPath) {
   if (!schemaPath || typeof schemaPath !== 'string' || !schemaPath.startsWith('#')) return null;
-  const parts = schemaPath.slice(1).split('/').filter(Boolean).map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  if (rootSchema === null || typeof rootSchema !== 'object') return null;
+
+  let byPath = _rankCache.get(rootSchema);
+  if (byPath === undefined) { byPath = new Map(); _rankCache.set(rootSchema, byPath); }
+  const hit = byPath.get(schemaPath);
+  if (hit !== undefined) return hit;
+
+  const rank = _computeRank(rootSchema, schemaPath);
+  byPath.set(schemaPath, rank);
+  return rank;
+}
+
+function _computeRank(rootSchema, schemaPath) {
   const rank = [];
   let node = rootSchema;
-  for (const seg of parts) {
+  let start = 1;
+  while (start <= schemaPath.length) {
+    let end = schemaPath.indexOf('/', start);
+    if (end < 0) end = schemaPath.length;
+    if (end === start) { start = end + 1; continue; }   // what filter(Boolean) dropped
+    const seg = unescapePointerSegment(schemaPath.slice(start, end));
+    start = end + 1;
+
     if (node == null || typeof node !== 'object') break;
     if (Array.isArray(node)) {
       const idx = Number(seg);
@@ -386,7 +438,7 @@ function schemaOrderRank(rootSchema, schemaPath) {
       rank.push(idx);
       node = node[idx];
     } else {
-      const idx = Object.keys(node).indexOf(seg);
+      const idx = keyIndex(node, seg);
       if (idx < 0) break;
       rank.push(idx);
       node = node[seg];
@@ -940,6 +992,13 @@ class Validator {
               };
     }
     this._applyDefaults = preprocess;
+    // Whether validate() can change the caller's object before the verdict.
+    // This is a capability, not an option: `useDefaults` is on by default, but
+    // buildDefaultsApplier returns null when the schema declares no defaults,
+    // so a plain schema is genuinely non-mutating. The renderers refuse to
+    // synthesize a frame when this is true, because a frame built from mutated
+    // data would show the reader a value they never sent.
+    this._mutatesInput = !!(preprocess || options.coerceTypes || options.removeAdditional);
     this._preprocess = preprocess;
 
     // Detect if schema is "selective" -- doesn't recurse into arrays/deep objects.
@@ -1374,6 +1433,16 @@ class Validator {
                       schemaFile: self._source ? self._source.path : undefined,
                     }))
                   : raw;
+                // Correlation is published, never applied. Both halves of a
+                // typo pair stay in the array; `related` only says they are
+                // one mistake, so a wrong pairing costs a sentence rather
+                // than a hidden violation.
+                if (enrich && cached.length > 1) attachRelated(cached);
+                // No diagnostic payload here. validate(data) is the library
+                // hot path, and attaching one cost about 100 ns per rejection
+                // for a consumer that never renders. The text path attaches
+                // it below, and a renderer given `{ data }` builds frames for
+                // object input on request.
               }
               return cached;
             },
@@ -1399,21 +1468,34 @@ class Validator {
           if (result && !result.valid && result.errors && result.errors.length) {
             // If errors came from the inner path that already ran through the
             // wrapped this.validate (codegen jsonValidateFn -> validate path),
-            // they may already be enriched. Detect by presence of `code`.
+            // they may already be enriched. Detect by presence of `docUrl`:
+            // only enrich() sets it. `code` is not a safe signal because
+            // branch-collapse attaches codes to raw errors, and detecting on
+            // it left every collapsed oneOf/anyOf error unenriched on the
+            // text path.
             const first = result.errors[0];
-            if (!first || !first.code) {
+            // Re-parse the input once so the enrich pass can pluck `received`
+            // and feed the suggestion engine (required-typo, format hints,
+            // coercion nudges all need the live value tree), and so the
+            // diagnostic payload carries the data on both paths below.
+            let parsedData;
+            try { parsedData = JSON.parse(jsonStr); } catch { parsedData = undefined; }
+            if (!first || !first.docUrl) {
               const positions = (this._lastRawInput != null) ? this._posCache.get(this._lastRawInput) : null;
-              // Re-parse the input once so the enrich pass can pluck `received`
-              // and feed the suggestion engine (required-typo, format hints,
-              // coercion nudges all need the live value tree).
-              let parsedData;
-              try { parsedData = JSON.parse(jsonStr); } catch { parsedData = undefined; }
               const enriched = result.errors.map((e) => enrich(e, {
                 data: parsedData,
                 positions,
                 schemaPositions: this._schemaPositions,
                 schemaFile: this._source ? this._source.path : undefined,
               }));
+              if (enriched.length > 1) attachRelated(enriched);
+              attachDiagnosticSource(enriched, {
+                data: parsedData,
+                text: jsonStr,
+                positions,
+                schema: this._schemaObj,
+                mutatesInput: this._mutatesInput === true,
+              });
               if (positions) this._posCache.reset();
               this._lastRawInput = null;
               return { valid: false, errors: enriched };
@@ -1430,6 +1512,13 @@ class Validator {
               }
               this._posCache.reset();
             }
+            if (result.errors.length > 1) attachRelated(result.errors);
+            attachDiagnosticSource(result.errors, {
+              data: parsedData,
+              text: jsonStr,
+              schema: this._schemaObj,
+              mutatesInput: this._mutatesInput === true,
+            });
           }
           this._lastRawInput = null;
           return result;
@@ -1893,6 +1982,26 @@ function _walkPointer (root, pointer) {
 // inflate the gzipped bundle beyond the size budget). Consumers who want
 // suggestions pass the error array through this helper after validation.
 // AOT errors don't carry `received`, so we re-derive it from `data` here.
+const { setDiagnosticSource } = require('./lib/diagnostic-source');
+const attachDiagnosticSource = setDiagnosticSource;
+
+// Resolved once. A require() inside the function was re-resolving the path
+// on every rejection, which the profile showed as internalModuleStat at the
+// top of the reject path, above the correlation it was loading.
+let _correlateTypos = null;
+function attachRelated (errors) {
+  if (_correlateTypos === null) _correlateTypos = require('./lib/correlate').correlateTypos;
+  const pairs = _correlateTypos(errors);
+  if (pairs === null) return errors;
+  for (const [from, to] of pairs) {
+    const e = errors[from];
+    if (!e) continue;
+    if (e.related) { if (!e.related.includes(to)) e.related.push(to); }
+    else e.related = [to];
+  }
+  return errors;
+}
+
 function attachSuggestions (errors, data) {
   if (!errors) return errors;
   for (const e of errors) {
@@ -1909,6 +2018,9 @@ function attachSuggestions (errors, data) {
     const s = suggestFor(probe, data);
     if (s) e.suggestion = s;
   }
+  // AOT modules import nothing, so this is their only route to a frame. The
+  // caller holds the original object and ran no preprocessing through here.
+  attachDiagnosticSource(errors, { data, mutatesInput: false });
   return errors;
 }
 

package/lib/correlate.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const { levenshtein } = require('./levenshtein');
+
+const MAX_DISTANCE = 2;
+
+/**
+ * Pair a `required` error naming a missing property with an
+ * `additionalProperties` error naming an extra property, when the two names
+ * are close enough to be one typo and nothing else in the same container is
+ * equally close.
+ *
+ * The tie checks are the point. `suggestRequiredTypo` in lib/suggestions.js
+ * takes the first key within distance 2 and does not check for ties, which is
+ * fine for a hint appended to an error that stands on its own. It is not fine
+ * as a reason to present two errors as one problem: an ambiguous pairing would
+ * tell the reader a confident story about the wrong key.
+ *
+ * Nothing is deleted. The result is a symmetric index map that callers may use
+ * to group; every error stays in the array.
+ *
+ * @param {Array} errors enriched or raw validation errors
+ * @returns {Map<number, number>|null} symmetric index pairs, null when there are none
+ */
+function correlateTypos (errors) {
+  if (!Array.isArray(errors) || errors.length < 2) return null;
+
+  // Most rejections have no candidate pair at all. Find that out with one
+  // pass over the keywords before allocating anything.
+  let sawMissing = false;
+  let sawExtra = false;
+  for (let i = 0; i < errors.length; i++) {
+    const e = errors[i];
+    if (!e) continue;
+    if (e.keyword === 'required') sawMissing = true;
+    else if (e.keyword === 'additionalProperties') sawExtra = true;
+    if (sawMissing && sawExtra) break;
+  }
+  if (!sawMissing || !sawExtra) return null;
+
+  const out = new Map();
+
+  // Bucket by container pointer. A missing key in one object has nothing to do
+  // with an extra key in another.
+  const byContainer = new Map();
+  for (let i = 0; i < errors.length; i++) {
+    const e = errors[i];
+    if (!e || !e.params) continue;
+    const missing = e.keyword === 'required' ? e.params.missingProperty : undefined;
+    const additional = e.keyword === 'additionalProperties' ? e.params.additionalProperty : undefined;
+    if (typeof missing !== 'string' && typeof additional !== 'string') continue;
+    const key = e.instancePath != null ? e.instancePath : (e.path || '');
+    let bucket = byContainer.get(key);
+    if (!bucket) { bucket = { missing: [], extra: [] }; byContainer.set(key, bucket); }
+    if (typeof missing === 'string') bucket.missing.push({ index: i, name: missing });
+    else bucket.extra.push({ index: i, name: additional });
+  }
+
+  for (const bucket of byContainer.values()) {
+    if (bucket.missing.length === 0 || bucket.extra.length === 0) continue;
+
+    // Full distance table for this container. Sizes here are the number of
+    // wrong keys in one object, so this stays small in practice.
+    const dist = [];
+    for (let m = 0; m < bucket.missing.length; m++) {
+      dist.push([]);
+      for (let x = 0; x < bucket.extra.length; x++) {
+        const d = levenshtein(bucket.missing[m].name, bucket.extra[x].name, MAX_DISTANCE);
+        dist[m].push(d);
+      }
+    }
+
+    for (let m = 0; m < bucket.missing.length; m++) {
+      // Best extra key for this missing key, and whether it is unique.
+      let bestX = -1;
+      let bestD = Infinity;
+      let tied = false;
+      for (let x = 0; x < bucket.extra.length; x++) {
+        const d = dist[m][x];
+        if (d < bestD) { bestD = d; bestX = x; tied = false; }
+        else if (d === bestD && d !== Infinity) tied = true;
+      }
+      if (bestX === -1 || tied) continue;
+      if (!(bestD > 0 && bestD <= MAX_DISTANCE)) continue;
+
+      // And the same question from the other side: is this missing key the
+      // unambiguous best match for that extra key?
+      let backM = -1;
+      let backD = Infinity;
+      let backTied = false;
+      for (let m2 = 0; m2 < bucket.missing.length; m2++) {
+        const d = dist[m2][bestX];
+        if (d < backD) { backD = d; backM = m2; backTied = false; }
+        else if (d === backD && d !== Infinity) backTied = true;
+      }
+      if (backTied || backM !== m) continue;
+
+      out.set(bucket.missing[m].index, bucket.extra[bestX].index);
+      out.set(bucket.extra[bestX].index, bucket.missing[m].index);
+    }
+  }
+
+  return out.size === 0 ? null : out;
+}
+
+module.exports = { correlateTypos };

package/lib/data-positions.js

@@ -52,7 +52,7 @@ function buildDataPositionMap (input) {
     return '/' + path.map(escapePtr).join('/');
   }
 
-  function walk (path) {
+  function walk (path, keySpan) {
     skipWs();
     if (i >= n) return;
     const start = i;
@@ -66,11 +66,22 @@ function buildDataPositionMap (input) {
         if (text.charCodeAt(i) === 0x7d) { i++; break; }
         if (text.charCodeAt(i) === 0x2c) { i++; continue; }
         skipWs();
+        // Record the key token before consuming it. The caret for an error
+        // that names a property belongs on the property, not on the value and
+        // not on the enclosing object.
+        const keyStart = i;
+        const keyPos = offsetToLineCol(keyStart);
         const key = readString();
+        const span = {
+          keyOffset: keyStart,
+          keyLength: i - keyStart,
+          keyLine: keyPos.line,
+          keyCol: keyPos.col,
+        };
         skipWs();
         if (text.charCodeAt(i) !== 0x3a) throw new Error('expected ":" at offset ' + i);
         i++;
-        walk(path.concat([key]));
+        walk(path.concat([key]), span);
       }
     } else if (ch === 0x5b) {
       i++;
@@ -93,7 +104,14 @@ function buildDataPositionMap (input) {
     }
 
     const length = i - start;
-    map[pointerOf(path)] = { byteOffset: start, length, line: pos.line, col: pos.col, text: pos.text };
+    const entry = { byteOffset: start, length, line: pos.line, col: pos.col, text: pos.text };
+    if (keySpan) {
+      entry.keyOffset = keySpan.keyOffset;
+      entry.keyLength = keySpan.keyLength;
+      entry.keyLine = keySpan.keyLine;
+      entry.keyCol = keySpan.keyCol;
+    }
+    map[pointerOf(path)] = entry;
   }
 
   if (text.charCodeAt(0) === 0xfeff) i = 1;

package/lib/diagnose.js

@@ -0,0 +1,312 @@
+'use strict';
+
+const { correlateTypos } = require('./correlate');
+const { buildDataPositionMap } = require('./data-positions');
+const { pathToDotted } = require('./render-shared');
+const { reprValue, expectedFor } = require('./enrich-error');
+
+const MAX_SYNTHESIZED_BYTES = 256 * 1024;
+
+/**
+ * Turn a validation error array into presentation-ready diagnostics.
+ *
+ * Pure: no I/O, no ANSI, no terminal width, deterministic for a given input.
+ * That is deliberate. The merge below is the one place in this library that
+ * can present two problems as one, so it has to be provable as data rather
+ * than by grepping terminal output.
+ *
+ * @param {Array} errors validation errors, enriched or raw
+ * @param {{text?: string, data?: any, positions?: object, schema?: object, mutatesInput?: boolean}} [source]
+ * @returns {Array} diagnostics
+ */
+function toDiagnostics (errors, source) {
+  if (!Array.isArray(errors) || errors.length === 0) return [];
+  const src = source || {};
+
+  const resolved = resolveFrames(src);
+  const pairs = correlateTypos(errors);
+
+  const diagnostics = [];
+  const consumed = new Set();
+
+  for (let i = 0; i < errors.length; i++) {
+    if (consumed.has(i)) continue;
+    const e = errors[i];
+    if (!e) continue;
+
+    const partner = pairs === null ? undefined : pairs.get(i);
+    if (partner !== undefined && !consumed.has(partner)) {
+      consumed.add(i);
+      consumed.add(partner);
+      diagnostics.push(mergedDiagnostic(errors, i, partner, resolved, src));
+      continue;
+    }
+
+    diagnostics.push(singleDiagnostic(e, i, resolved, src));
+  }
+
+  diagnostics.sort((a, b) => {
+    if (a.sortPos !== b.sortPos) return a.sortPos - b.sortPos;
+    if (a.rank !== b.rank) return a.rank - b.rank;
+    return a.pointer < b.pointer ? -1 : a.pointer > b.pointer ? 1 : 0;
+  });
+
+  for (const d of diagnostics) delete d.sortPos;
+  return diagnostics;
+}
+
+// Resolve one position map for the whole call, not one per error.
+function resolveFrames (src) {
+  const none = { positions: null, synthesized: false, refusal: null };
+  if (src.positions) return { positions: src.positions, synthesized: false, refusal: null };
+
+  if (src.text != null) {
+    try {
+      return { positions: buildDataPositionMap(src.text), synthesized: false, refusal: null };
+    } catch {
+      return none;
+    }
+  }
+
+  if (src.data === undefined) return none;
+
+  if (src.mutatesInput) {
+    // The object in hand is not what the caller sent. Drawing a caret under a
+    // coerced value or an injected default would be output that is wrong and
+    // draws no complaint, which is the failure mode this library treats as the
+    // worst one. Say why instead.
+    return {
+      positions: null,
+      synthesized: false,
+      refusal: 'no frame; the value was modified in place before validation (coerceTypes, useDefaults or removeAdditional)',
+    };
+  }
+
+  let text;
+  try {
+    text = JSON.stringify(src.data, null, 2);
+  } catch {
+    return none;
+  }
+  if (typeof text !== 'string') return none;
+  if (text.length > MAX_SYNTHESIZED_BYTES) {
+    // The string cannot be measured without being built. It is built, measured
+    // and dropped; there is no way to skip the allocation and still know.
+    return { positions: null, synthesized: false, refusal: 'no frame; the value is larger than 256 KB' };
+  }
+  try {
+    return { positions: buildDataPositionMap(text), synthesized: true, refusal: null };
+  } catch {
+    return none;
+  }
+}
+
+function frameFor (err, resolved) {
+  if (!resolved.positions) return frameFromError(err);
+  const path = err.instancePath != null ? err.instancePath : (err.path || '');
+  const named = (err.params && (err.params.additionalProperty || err.params.unevaluatedProperty)) || null;
+  const hit = (named && resolved.positions[path + '/' + named]) || resolved.positions[path];
+  if (!hit) return null;
+
+  // A caret on the key token when the error names a property, on the value
+  // otherwise. Never wider than the line it is drawn under.
+  const useKey = named != null && hit.keyOffset !== undefined;
+  const col = useKey ? hit.keyCol : hit.col;
+  const rawLen = useKey ? hit.keyLength : hit.length;
+  const lineLen = (hit.text || '').length;
+  const length = Math.max(1, Math.min(rawLen || 1, Math.max(1, lineLen - col + 1)));
+
+  return {
+    line: useKey ? hit.keyLine : hit.line,
+    col,
+    length,
+    text: hit.text,
+    spans: rawLen > length,
+    synthesized: resolved.synthesized,
+  };
+}
+
+// No position map in hand, but the error itself may carry one: validateJSON
+// attaches `dataFrame` and `anchor` at enrichment time, and errors handed
+// over from another process or a fixture arrive with only those.
+function frameFromError (err) {
+  const df = err.dataFrame;
+  if (!df || typeof df.line !== 'number') return null;
+  const a = err.anchor;
+  const named = (err.params && (err.params.additionalProperty || err.params.unevaluatedProperty)) || null;
+  const useKey = named != null && a && a.keyLine !== undefined;
+  const col = useKey ? a.keyCol : df.col;
+  const rawLen = useKey ? a.keyLength : df.length;
+  const lineLen = (df.text || '').length;
+  const length = Math.max(1, Math.min(rawLen || 1, Math.max(1, lineLen - col + 1)));
+  return {
+    line: useKey ? a.keyLine : df.line,
+    col,
+    length,
+    text: df.text,
+    spans: rawLen > length,
+    synthesized: false,
+  };
+}
+
+function headlineFor (err, src) {
+  const p = err.params || {};
+  switch (err.keyword) {
+    case 'additionalProperties':
+      return `unknown property "${p.additionalProperty}"`;
+    case 'unevaluatedProperties':
+      return `unevaluated property "${p.unevaluatedProperty}"`;
+    case 'required':
+      return `missing required property "${p.missingProperty}"`;
+    case 'oneOf': case 'anyOf': {
+      const disc = discriminatorFor(err, src);
+      if (disc) return `no variant matches ${disc.key} ${JSON.stringify(disc.value)}`;
+      return err.detail || err.message || 'no variant matched';
+    }
+    default:
+      return err.detail || err.message || 'validation failed';
+  }
+}
+
+// A discriminator is a property every branch pins with `const`, with distinct
+// values. Anything looser and the code does not guess.
+function discriminatorFor (err, src) {
+  const schema = src.schema;
+  const data = src.data;
+  if (!schema || !data || typeof data !== 'object') return null;
+  const branches = branchesAt(schema, err.schemaPath, err.keyword);
+  if (!Array.isArray(branches) || branches.length < 2) return null;
+
+  const first = branches[0] && branches[0].properties;
+  if (!first) return null;
+  for (const key of Object.keys(first)) {
+    const values = [];
+    let ok = true;
+    for (const b of branches) {
+      const prop = b && b.properties && b.properties[key];
+      if (!prop || prop.const === undefined) { ok = false; break; }
+      if (values.includes(prop.const)) { ok = false; break; }
+      values.push(prop.const);
+    }
+    if (!ok) continue;
+    const actual = data[key];
+    if (actual === undefined) continue;
+    return { key, value: actual };
+  }
+  return null;
+}
+
+// Branch errors arrive raw: keyword, message, instancePath, params. Give each
+// a copy carrying what was expected and what was found, so the note under a
+// composition failure reads as an observation rather than a rule. Copies,
+// never the originals: the array on the error object is a contract.
+function decorateBranches (subs, src) {
+  return subs.map((sub) => {
+    if (!sub || typeof sub !== 'object') return sub;
+    const copy = Object.assign({}, sub);
+    const exp = expectedFor(sub);
+    if (exp !== undefined) copy.expected = exp;
+    if (copy.received === undefined) {
+      const got = valueAt(src.data, sub.instancePath);
+      if (got !== null) copy.received = got;
+    }
+    if (Array.isArray(sub.branchErrors)) copy.branchErrors = decorateBranches(sub.branchErrors, src);
+    return copy;
+  });
+}
+
+// The value a JSON pointer names, as the same short repr enrich() uses for
+// `received`. Null when the data is not in hand or the path does not resolve.
+function valueAt (data, pointer) {
+  if (data === undefined || typeof pointer !== 'string') return null;
+  if (pointer === '') return reprValue(data);
+  let cur = data;
+  for (const seg of pointer.split('/').slice(1)) {
+    if (cur == null || typeof cur !== 'object') return null;
+    cur = cur[seg.replace(/~1/g, '/').replace(/~0/g, '~')];
+  }
+  return cur === undefined ? null : reprValue(cur);
+}
+
+// Walk `#/a/b/anyOf` down to the branch array it names.
+function branchesAt (schema, schemaPath, keyword) {
+  if (typeof schemaPath !== 'string' || !schemaPath.startsWith('#')) {
+    return schema[keyword];
+  }
+  const parts = schemaPath.slice(1).split('/').filter(Boolean).map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let cur = schema;
+  for (const part of parts) {
+    if (cur == null || typeof cur !== 'object') return null;
+    cur = cur[part];
+  }
+  return Array.isArray(cur) ? cur : null;
+}
+
+function singleDiagnostic (e, index, resolved, src) {
+  const pointer = e.instancePath != null ? e.instancePath : (e.path || '');
+  // A composition failure is reported at the container, but the closest
+  // branch already says where inside it the mismatch is. Point there.
+  const closest = e.branchErrors && e.branchErrors.length ? e.branchErrors[0] : null;
+  const anchorErr = closest && closest.instancePath ? closest : e;
+  const frame = frameFor(anchorErr, resolved);
+  // What was found at the caret. A branch error carries no `received`, so
+  // read it off the data when the data is in hand.
+  let found = e.received != null ? e.received : null;
+  if (anchorErr !== e) {
+    found = closest.received != null ? closest.received : valueAt(src.data, closest.instancePath);
+  }
+  const notes = [];
+  if (!frame && resolved.refusal) notes.push(resolved.refusal);
+  if (frame && frame.spans) notes.push('value continues past the end of this line');
+  if (e.docUrl) notes.push('see ' + e.docUrl);
+
+  return {
+    code: e.code,
+    headline: headlineFor(e, src),
+    pointer,
+    dotted: pathToDotted(anchorErr.instancePath != null ? anchorErr.instancePath : pointer),
+    frame,
+    found,
+    help: e.suggestion ? e.suggestion.text : null,
+    notes,
+    branchErrors: e.branchErrors ? decorateBranches(e.branchErrors, src) : null,
+    mergedFrom: [e],
+    rank: typeof e.rank === 'number' ? e.rank : 2,
+    sortPos: frame ? frame.line * 100000 + frame.col : index,
+  };
+}
+
+function mergedDiagnostic (errors, i, j, resolved, src) {
+  const a = errors[i];
+  const b = errors[j];
+  const missing = a.keyword === 'required' ? a : b;
+  const extra = a.keyword === 'required' ? b : a;
+  const missingName = missing.params.missingProperty;
+  const extraName = extra.params.additionalProperty;
+
+  // Anchor on the extra key: that token is the thing the reader edits. The
+  // missing half has no token to point at.
+  const frame = frameFor(extra, resolved);
+  const notes = [];
+  if (!frame && resolved.refusal) notes.push(resolved.refusal);
+  const docUrl = missing.docUrl || extra.docUrl;
+  if (docUrl) notes.push('see ' + docUrl);
+
+  const pointer = missing.instancePath != null ? missing.instancePath : (missing.path || '');
+  return {
+    code: missing.code,
+    headline: `unknown property "${extraName}"`,
+    pointer,
+    dotted: pathToDotted(pointer),
+    frame,
+    found: null,
+    help: `did you mean "${missingName}"?`,
+    notes,
+    branchErrors: null,
+    mergedFrom: [missing, extra],
+    rank: 0,
+    sortPos: frame ? frame.line * 100000 + frame.col : Math.min(i, j),
+  };
+}
+
+module.exports = { toDiagnostics };

package/lib/diagnostic-source.js

@@ -0,0 +1,46 @@
+'use strict';
+
+// Attach to an errors array the material a renderer needs to build frames:
+// the data, the original text when there was one, the schema, and whether
+// validate() changed the data before the verdict.
+//
+// It rides on the array as a non-enumerable symbol property, never on the
+// error objects. JSON.stringify, Object.keys, length and deep equality against
+// a fixture are unchanged. A WeakMap side table was tried and measured: it
+// keyed short-lived arrays, and the ephemeron work pushed the garbage
+// collector to a third of the reject path. A property costs about 80 ns and
+// nothing at collection time.
+const KEY = Symbol.for('ata.diagnosticSource');
+
+// One descriptor, reused. Building a fresh one per call was most of this
+// function's cost in the single-error profile, through the allocation and
+// the collection that followed it.
+const DESCRIPTOR = { value: null, enumerable: false, configurable: true, writable: true };
+
+function setDiagnosticSource (errors, payload) {
+  if (!Array.isArray(errors) || !payload || !Object.isExtensible(errors)) return errors;
+  const prev = errors[KEY];
+  let value = payload;
+  if (prev) {
+    // validateJSON's already-enriched path runs after the validate() wrapper
+    // has recorded the parsed data. Merge, so the text arrives without the
+    // data going missing.
+    value = Object.assign({}, prev);
+    for (const k of Object.keys(payload)) if (payload[k] !== undefined) value[k] = payload[k];
+  }
+  try {
+    DESCRIPTOR.value = value;
+    Object.defineProperty(errors, KEY, DESCRIPTOR);
+    DESCRIPTOR.value = null;
+  } catch {
+    // A validator that throws from its own error path is worse than a
+    // missing frame. The renderer degrades to pointer-only output.
+  }
+  return errors;
+}
+
+function getDiagnosticSource (errors) {
+  return (Array.isArray(errors) && errors[KEY]) || null;
+}
+
+module.exports = { setDiagnosticSource, getDiagnosticSource };

package/lib/enrich-error.js

@@ -35,6 +35,7 @@ function expectedFor (err) {
     case 'minimum': return err.params && err.params.limit != null ? `≥${err.params.limit}` : undefined;
     case 'maximum': return err.params && err.params.limit != null ? `≤${err.params.limit}` : undefined;
     case 'format': return err.params && err.params.format ? `format '${err.params.format}'` : undefined;
+    case 'pattern': return err.params && err.params.pattern ? `string matching /${err.params.pattern}/` : undefined;
     case 'enum': return err.params && err.params.allowedValues
       ? `one of [${err.params.allowedValues.map(reprValue).join(', ')}]`
       : undefined;
@@ -73,6 +74,59 @@ function pickReceived (err, data) {
  * Pure: returns a new object. Source frames and suggestions are added by
  * other helpers later in the pipeline.
  */
+// Observation-first wording. `message` stays as it is for parity, so this is a
+// separate field a consumer opts into.
+function detailFor (err, out) {
+  const p = err.params || {};
+  switch (err.keyword) {
+    case 'type':
+      return `expected ${p.type}, found ${typeNameOf(out.received)}`;
+    case 'required':
+      return `missing required property "${p.missingProperty}"`;
+    case 'additionalProperties':
+      return `unknown property "${p.additionalProperty}"`;
+    case 'unevaluatedProperties':
+      return `unevaluated property "${p.unevaluatedProperty}"`;
+    case 'enum':
+      return out.expected ? `expected ${out.expected}, found ${out.received}` : undefined;
+    case 'const':
+      return out.expected ? `expected ${out.expected}, found ${out.received}` : undefined;
+    case 'format':
+      return `not a valid ${p.format}: ${out.received}`;
+    case 'minimum': case 'maximum': case 'exclusiveMinimum': case 'exclusiveMaximum':
+      return `expected ${out.expected}, found ${out.received}`;
+    case 'minLength': case 'maxLength':
+      return `expected ${out.expected}, found ${out.received}`;
+    default:
+      return out.expected ? `expected ${out.expected}, found ${out.received}` : undefined;
+  }
+}
+
+// Derived from the repr in `received`, which is already a JSON-ish string.
+function typeNameOf (received) {
+  if (received === undefined) return 'nothing';
+  if (received === 'null') return 'null';
+  if (received === 'true' || received === 'false') return 'boolean';
+  if (received.startsWith('"')) return 'string';
+  if (received.startsWith('[array')) return 'array';
+  if (received.startsWith('{') || received.startsWith('[object')) return 'object';
+  if (/^-?\d/.test(received)) return 'number';
+  return 'value';
+}
+
+// Cause before effect, applied only as a tie-break within one container.
+// Ordering across the document is by position, done in the renderer.
+const RANK = {
+  required: 0, additionalProperties: 0, unevaluatedProperties: 0,
+  unevaluatedItems: 0, dependentRequired: 0, propertyNames: 0,
+  type: 1,
+  oneOf: 3, anyOf: 3, allOf: 3, not: 3,
+};
+function rankFor (keyword) {
+  const r = RANK[keyword];
+  return r === undefined ? 2 : r;
+}
+
 function enrich (rawErr, opts) {
   const data = opts && opts.data;
   const positions = opts && opts.positions;
@@ -129,6 +183,28 @@ function enrich (rawErr, opts) {
   const sugg = suggestFor(out, opts && opts.data);
   if (sugg) out.suggestion = sugg;
 
+  const detail = detailFor(rawErr, out);
+  if (detail !== undefined) out.detail = detail;
+  out.rank = rankFor(keyword);
+
+  // Token-level anchor. `dataFrame` already carries the value span; `anchor`
+  // adds the key span so a caret can sit on the property that is wrong rather
+  // than on the object containing it.
+  if (opts && opts.positions) {
+    const named = (rawErr.params && (rawErr.params.additionalProperty || rawErr.params.unevaluatedProperty)) || null;
+    const own = opts.positions[path];
+    const child = named ? opts.positions[(path === '' ? '' : path) + '/' + named] : null;
+    const src = child || own;
+    if (src) {
+      out.anchor = { line: src.line, col: src.col, length: src.length };
+      if (src.keyOffset !== undefined) {
+        out.anchor.keyLine = src.keyLine;
+        out.anchor.keyCol = src.keyCol;
+        out.anchor.keyLength = src.keyLength;
+      }
+    }
+  }
+
   return out;
 }
 

package/lib/js-compiler.js

@@ -1492,9 +1492,17 @@ function compileToJSCodegen(schema, schemaMap, userFormats) {
 function replaceTopLevel(code) {
   let fnDepth = 0, result = '', i = 0
   while (i < code.length) {
-    if (code.startsWith('function', i) && (i === 0 || /[^a-zA-Z_$]/.test(code[i - 1]))) {
-      // Found a nested function — skip to opening brace, track all braces inside
-      let j = i + 8
+    // A nested closure keeps its own returns. Both spellings count: a
+    // `function` keyword and an arrow with a block body. The inline pattern
+    // compiler emits `(()=>{...return false...return true})()` and rewriting
+    // those returns turned the arrow's boolean into an object, which made
+    // `!(cond && obj)` false and let the hybrid accept what the boolean
+    // program rejected.
+    const isFunctionKw = code.startsWith('function', i) && (i === 0 || /[^a-zA-Z_$]/.test(code[i - 1]))
+    const isArrowBlock = code.startsWith('=>{', i)
+    if (isFunctionKw || isArrowBlock) {
+      // Skip to the opening brace, then track all braces inside the body.
+      let j = isArrowBlock ? i + 2 : i + 8
       while (j < code.length && code[j] !== '{') j++
       result += code.slice(i, j + 1)
       i = j + 1

package/lib/levenshtein.js

@@ -2,14 +2,25 @@
 
 // Bounded Levenshtein. Returns Infinity if distance > maxDistance.
 // Single-row DP. O(n*m) worst case but typical strings are <30 chars.
+// Two rows of scratch, reused across calls. The function is not recursive
+// and the library is single-threaded, so nothing else is using them; growing
+// them once beats allocating two arrays on every comparison, which the
+// reject-path profile showed as most of this function's cost.
+let scratchA = new Int32Array(64);
+let scratchB = new Int32Array(64);
+
 function levenshtein (a, b, maxDistance) {
   const max = maxDistance == null ? Infinity : maxDistance;
   if (a === b) return 0;
   if (Math.abs(a.length - b.length) > max) return Infinity;
   if (a.length === 0) return b.length;
   if (b.length === 0) return a.length;
-  let prev = new Array(b.length + 1);
-  let curr = new Array(b.length + 1);
+  if (scratchA.length < b.length + 1) {
+    scratchA = new Int32Array(b.length + 1);
+    scratchB = new Int32Array(b.length + 1);
+  }
+  let prev = scratchA;
+  let curr = scratchB;
   for (let j = 0; j <= b.length; j++) prev[j] = j;
   for (let i = 1; i <= a.length; i++) {
     curr[0] = i;

package/lib/render-compact.js

@@ -1,31 +1,41 @@
 'use strict';
 
-const { color, ANSI, resolveColor, pathToDotted, trimCwd } = require('./render-shared');
+const { color, ANSI, resolveColor, trimCwd } = require('./render-shared');
+const { toDiagnostics } = require('./diagnose');
+
+const { getDiagnosticSource } = require('./diagnostic-source');
 
 function renderCompact (errors, opts) {
   if (!Array.isArray(errors) || errors.length === 0) return '';
   opts = opts || {};
   const useColor = resolveColor(opts.color || 'auto');
   const cwd = opts.cwd;
+  const carried = getDiagnosticSource(errors) || {};
+  const source = opts.data !== undefined ? Object.assign({}, carried, { data: opts.data }) : carried;
+  const diags = toDiagnostics(errors, source);
   const lines = [];
 
-  for (const err of errors) {
+  for (const d of diags) {
     let prefix = '';
-    if (err.schemaSource) {
-      const f = trimCwd(err.schemaSource.file, cwd);
-      prefix = color(useColor, ANSI.cyan, `${f}:${err.schemaSource.line}:${err.schemaSource.col}`) + ' - ';
+    const raw = d.mergedFrom[0];
+    if (raw && raw.schemaSource) {
+      const f = trimCwd(raw.schemaSource.file, cwd);
+      prefix = color(useColor, ANSI.cyan, `${f}:${raw.schemaSource.line}:${raw.schemaSource.col}`) + ' - ';
     }
-    const codeStr = color(useColor, ANSI.red + ANSI.bold, `error ${err.code}`);
-    const pathStr = color(useColor, ANSI.cyan, pathToDotted(err.path));
-    const got = err.received != null ? `got ${err.received}` : '';
-    const sugg = err.suggestion ? color(useColor, ANSI.yellow, `, ${err.suggestion.text}`) : '';
+    const codeStr = color(useColor, ANSI.red + ANSI.bold, d.code ? `error ${d.code}` : 'error');
+    const pathStr = color(useColor, ANSI.cyan, d.dotted);
+    const got = raw && raw.received != null ? `got ${raw.received}` : '';
+    const sugg = d.help ? color(useColor, ANSI.yellow, `, ${d.help}`) : '';
     const tail = got || sugg ? ` (${got}${sugg})` : '';
-    lines.push(`${prefix}${codeStr}: ${pathStr} ${err.message}${tail}`);
+    lines.push(`${prefix}${codeStr}: ${pathStr} ${d.headline}${tail}`);
   }
 
   const n = errors.length;
+  const shown = diags.length;
   lines.push('');
-  lines.push(`Found ${n} error${n === 1 ? '' : 's'} in ${opts.context || 'input'}.`);
+  let summary = `Found ${n} error${n === 1 ? '' : 's'} in ${opts.context || 'input'}`;
+  if (shown !== n) summary += `, shown as ${shown} diagnostic${shown === 1 ? '' : 's'}`;
+  lines.push(summary + '.');
   if (!(process.stdout && process.stdout.isTTY)) {
     lines.push('(run with --pretty for source frames)');
   }

package/lib/render-pretty.js

@@ -1,60 +1,93 @@
 'use strict';
 
 const { color, ANSI, resolveColor, trimCwd, truncateLine, terminalWidth } = require('./render-shared');
+const { toDiagnostics } = require('./diagnose');
 
+const { getDiagnosticSource } = require('./diagnostic-source');
+
+function sourceFor (errors, opts) {
+  const carried = getDiagnosticSource(errors) || {};
+  if (opts.data !== undefined) return Object.assign({}, carried, { data: opts.data });
+  return carried;
+}
+
+// Never wider than the terminal. The old form repeated the caret for the
+// full span of the value, which for a root-level error was the whole
+// document drawn under a one-character line.
 function caretLine (col, length, gutter) {
   const pad = ' '.repeat(gutter);
   const lead = ' '.repeat(Math.max(0, col - 1));
-  const carets = '^'.repeat(Math.max(1, length || 1));
+  const carets = '^'.repeat(Math.max(1, Math.min(length || 1, terminalWidth())));
   return pad + '| ' + lead + carets;
 }
 
-function renderOne (err, useColor, opts) {
+// What sits beside the caret. For a value error, the value that was found.
+// For a missing property there is no value to show, and the useful fact is
+// what was expected. For errors about the container's shape or about which
+// branch matched, printing the whole container is noise, so nothing.
+const NO_SUFFIX = new Set(['additionalProperties', 'unevaluatedProperties', 'unevaluatedItems', 'dependentRequired', 'propertyNames', 'oneOf', 'anyOf', 'allOf', 'not']);
+function caretSuffix (d, raw, useColor) {
+  if (!raw) return '';
+  if (raw.keyword === 'required') {
+    return raw.expected ? '  ' + color(useColor, ANSI.dim, `expected ${raw.expected}`) : '';
+  }
+  // A composition error anchored inside the closest branch has a value there.
+  if (d.found != null && (raw.keyword === 'oneOf' || raw.keyword === 'anyOf')) {
+    return '  ' + color(useColor, ANSI.dim, `found ${d.found}`);
+  }
+  if (NO_SUFFIX.has(raw.keyword)) return '';
+  return d.found != null ? '  ' + color(useColor, ANSI.dim, `found ${d.found}`) : '';
+}
+
+function renderOne (d, useColor, opts) {
   const lines = [];
-  const cwd = opts.cwd;
   const width = terminalWidth();
   const gutter = 3;
 
-  // Headline
-  const headline = `${err.message}`;
-  lines.push(color(useColor, ANSI.red + ANSI.bold, `error[${err.code}]: `) + headline);
+  // Headline carries the code when there is one. A code-less error, which the
+  // LazyRejection fallback can produce, must not render as "error[undefined]".
+  const label = d.code ? `error[${d.code}]: ` : 'error: ';
+  lines.push(color(useColor, ANSI.red + ANSI.bold, label) + d.headline);
 
-  // Schema source frame
-  if (err.schemaSource) {
-    const f = trimCwd(err.schemaSource.file, cwd);
-    lines.push(`  --> ${color(useColor, ANSI.cyan, `${f}:${err.schemaSource.line}:${err.schemaSource.col}`)}`);
+  // Schema source frame, when the Validator was built with a `source` option.
+  // This is the part that makes the output read like a compiler, and it must
+  // survive the rewrite: it points at the rule, where the data frame below
+  // points at the value.
+  const raw = d.mergedFrom[0];
+  if (raw && raw.schemaSource) {
+    const f = trimCwd(raw.schemaSource.file, opts.cwd);
+    lines.push(`  --> ${color(useColor, ANSI.cyan, `${f}:${raw.schemaSource.line}:${raw.schemaSource.col}`)}`);
     lines.push('   |');
-    const ln = String(err.schemaSource.line).padStart(2, ' ');
-    const srcText = truncateLine(err.schemaSource.text, width - 8);
-    lines.push(` ${ln} | ${srcText}`);
-    const inlineHint = err.expected ? '  ' + color(useColor, ANSI.dim, `expected ${err.expected}`) : '';
-    lines.push(caretLine(err.schemaSource.col, 1, gutter) + inlineHint);
+    const sln = String(raw.schemaSource.line).padStart(2, ' ');
+    lines.push(` ${sln} | ${truncateLine(raw.schemaSource.text, width - 8)}`);
+    const inlineHint = raw.expected ? '  ' + color(useColor, ANSI.dim, `expected ${raw.expected}`) : '';
+    lines.push(caretLine(raw.schemaSource.col, 1, gutter) + inlineHint);
     lines.push('   |');
   }
 
-  // Data frame
-  if (err.dataFrame) {
-    lines.push(`  --> ${color(useColor, ANSI.dim, `input, byte ${err.dataFrame.byteOffset}`)}`);
+  // Data location, always, even without a frame. This is the single most
+  // common reason today's output cannot be acted on.
+  if (d.frame) {
+    const where = `input:${d.frame.line}:${d.frame.col}`;
+    lines.push(`  --> ${color(useColor, ANSI.cyan, where)}  ${color(useColor, ANSI.dim, '(' + d.dotted + ')')}`);
     lines.push('   |');
-    const ln = String(err.dataFrame.line).padStart(2, ' ');
-    const srcText = truncateLine(err.dataFrame.text, width - 8);
-    lines.push(` ${ln} | ${srcText}`);
-    const got = err.received != null ? '  ' + color(useColor, ANSI.dim, `got ${err.received}`) : '';
-    lines.push(caretLine(err.dataFrame.col, err.dataFrame.length, gutter) + got);
+    const ln = String(d.frame.line).padStart(2, ' ');
+    lines.push(` ${ln} | ${truncateLine(d.frame.text, width - 8)}`);
+    lines.push(caretLine(d.frame.col, d.frame.length, gutter) + caretSuffix(d, raw, useColor));
     lines.push('   |');
+  } else {
+    lines.push(`  --> ${color(useColor, ANSI.cyan, 'at ' + d.dotted)}`);
   }
 
-  if (err.suggestion) {
-    lines.push('   = ' + color(useColor, ANSI.yellow, 'help: ') + err.suggestion.text);
-  }
-  if (err.branchErrors && err.branchErrors.length) {
-    const variant = (err.params && err.params.closestName) || 'closest variant';
-    const n = err.branchErrors.length;
+  if (d.help) lines.push('   = ' + color(useColor, ANSI.yellow, 'help: ') + d.help);
+  if (d.branchErrors && d.branchErrors.length) {
+    const variant = (raw && raw.params && raw.params.closestName) || 'closest variant';
+    const n = d.branchErrors.length;
     lines.push('   = ' + color(useColor, ANSI.dim, 'note: ') + `closest match was ${variant} with ${n} error${n === 1 ? '' : 's'}:`);
-    renderBranchErrors(err.branchErrors, 1, lines, useColor);
+    renderBranchErrors(d.branchErrors, 1, lines, useColor);
   }
-  if (err.docUrl) {
-    lines.push('   = ' + color(useColor, ANSI.dim, 'note: see ') + err.docUrl);
+  for (const note of d.notes) {
+    lines.push('   = ' + color(useColor, ANSI.dim, 'note: ') + note);
   }
   return lines.join('\n');
 }
@@ -70,7 +103,12 @@ function renderBranchErrors (subs, depth, lines, useColor) {
   const max = 3;
   const shown = subs.slice(0, max);
   for (const sub of shown) {
-    lines.push('       ' + color(useColor, ANSI.dim, `${sub.keyword}: ${sub.message || ''}`));
+    // Observation first when the branch error carries one; the rule otherwise.
+    let text = sub.message || '';
+    if (sub.expected !== undefined) {
+      text = `expected ${sub.expected}` + (sub.received !== undefined ? `, found ${sub.received}` : '');
+    }
+    lines.push('       ' + color(useColor, ANSI.dim, `${sub.keyword}: ${text}`));
     if (sub.branchErrors && sub.branchErrors.length) renderBranchErrors(sub.branchErrors, depth + 1, lines, useColor);
   }
   if (subs.length > max) {
@@ -85,17 +123,28 @@ function renderPretty (errors, opts) {
   const maxErrors = opts.maxErrors != null ? opts.maxErrors : 20;
   const context = opts.context || 'input';
 
+  const diags = toDiagnostics(errors, sourceFor(errors, opts));
+
   const blocks = [];
-  const limit = maxErrors === 0 ? errors.length : Math.min(maxErrors, errors.length);
-  for (let i = 0; i < limit; i++) {
-    blocks.push(renderOne(errors[i], useColor, opts));
-  }
+  const limit = maxErrors === 0 ? diags.length : Math.min(maxErrors, diags.length);
+  for (let i = 0; i < limit; i++) blocks.push(renderOne(diags[i], useColor, opts));
+
   let out = blocks.join('\n\n');
-  if (limit < errors.length) {
-    out += `\n\n... and ${errors.length - limit} more errors (run with --pretty --max-errors=0 to see all)`;
+  if (limit < diags.length) {
+    out += `\n\n... and ${diags.length - limit} more errors (run with --pretty --max-errors=0 to see all)`;
   }
+  // The count never drifts from errors.length. When correlation collapsed a
+  // pair the second clause says so, so the reader can reconcile the two.
   const n = errors.length;
-  out += `\n\n` + color(useColor, ANSI.red + ANSI.bold, `error: `) + `${n} schema violation${n === 1 ? '' : 's'} in ${context}`;
+  const shown = diags.length;
+  let summary = `${n} schema violation${n === 1 ? '' : 's'} in ${context}`;
+  if (shown !== n) summary += `, shown as ${shown} diagnostic${shown === 1 ? '' : 's'}`;
+  out += '\n\n' + color(useColor, ANSI.red + ANSI.bold, 'error: ') + summary;
+  // Said once, not under every block. The reader needs to know their line
+  // numbers will not match a file, and needs to be told one time.
+  if (diags.some((d) => d.frame && d.frame.synthesized)) {
+    out += '\n' + color(useColor, ANSI.dim, 'note: frames were reconstructed from the value, not from your input text; line numbers refer to that reconstruction');
+  }
   return out;
 }
 

package/lib/version.js

@@ -7,4 +7,4 @@
 //
 // Kept in lockstep with package.json by `tests/test_version_sync.js`.
 
-module.exports = '1.8.1';
+module.exports = '1.9.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "JSON Schema validation with first-class TypeScript and zero runtime cost. AOT compile to per-schema ESM modules with zero validator dependency. Generic Validator<T> for TypeBox/Zod/Valibot composition. Optional runtime API. Standard Schema V1 compatible.",
   "main": "index.js",
   "module": "index.mjs",
@@ -44,7 +44,7 @@
     "release:check": "node scripts/regen-safe-regex-source.js && node tests/test_pack_purity.js && node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js && node tests/test_safe_regex_source_sync.js && node tests/test_version_sync.js",
     "build": "cmake-js build --target ata",
     "rebuild": "cmake-js rebuild --target ata",
-    "test": "node test.js && node tests/test_removed_aot_methods.js && node tests/test_no_native.js && node tests/test_no_eval.js && node tests/test_property_dependencies.js && node tests/test_v1_dialect.js && node tests/test_buffer_path_parity.js && node tests/test_buffer_gate.js && node tests/test_draft7_semantics.js && node tests/test_metaschema_ref.js && node tests/test_pure_js_unsupported.js && node tests/test_native_load_order.js && node tests/test_pack_purity.js && node tests/test_make_native_package.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_native_loaded.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_format_mode.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.js && node tests/test_engine_diagnostic.js && node tests/test_format_engine_parity.js && node tests/test_defs_pointer_alias.js && node tests/test_cross_doc_root_ref.js && node tests/test_codegen_entrypoint_agreement.js && node tests/test_pattern_properties_errors.js && node tests/test_no_input_mutation.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_error_code_lookup.js && node tests/test_error_order.js && node tests/test_value_equality.js && node tests/test_vocabulary.js && node tests/test_schema_scan.js && node tests/test_lazy_errors.js && node tests/test_plan_compiler.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_enrich_received.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
+    "test": "node test.js && node tests/test_removed_aot_methods.js && node tests/test_no_native.js && node tests/test_no_eval.js && node tests/test_property_dependencies.js && node tests/test_v1_dialect.js && node tests/test_buffer_path_parity.js && node tests/test_buffer_gate.js && node tests/test_draft7_semantics.js && node tests/test_metaschema_ref.js && node tests/test_pure_js_unsupported.js && node tests/test_native_load_order.js && node tests/test_pack_purity.js && node tests/test_make_native_package.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_native_loaded.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_format_mode.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.js && node tests/test_engine_diagnostic.js && node tests/test_format_engine_parity.js && node tests/test_defs_pointer_alias.js && node tests/test_cross_doc_root_ref.js && node tests/test_codegen_entrypoint_agreement.js && node tests/test_hybrid_agreement.js && node tests/test_ajv_errors.js && node tests/test_pattern_properties_errors.js && node tests/test_no_input_mutation.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_error_code_lookup.js && node tests/test_error_order.js && node tests/test_value_equality.js && node tests/test_vocabulary.js && node tests/test_schema_scan.js && node tests/test_lazy_errors.js && node tests/test_plan_compiler.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_enrich_received.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_additive_fields.js && node tests/test_diagnostic_source.js && node tests/test_diagnose.js && node tests/test_correlate.js && node tests/test_diagnostics_score.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
     "bench:size": "node benchmark/bench_aot_size.mjs",
     "test:suite": "node tests/run_suite.js && node tests/run_suite.js draft7 && node tests/run_suite.js v1",
     "test:compat": "node tests/test_compat.js",
@@ -112,13 +112,13 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.8.1",
-    "@ata-validator/native-darwin-x64": "1.8.1",
-    "@ata-validator/native-linux-x64-gnu": "1.8.1",
-    "@ata-validator/native-linux-arm64-gnu": "1.8.1",
-    "@ata-validator/native-linux-x64-musl": "1.8.1",
-    "@ata-validator/native-linux-arm64-musl": "1.8.1",
-    "@ata-validator/native-win32-x64": "1.8.1"
+    "@ata-validator/native-darwin-arm64": "1.9.0",
+    "@ata-validator/native-darwin-x64": "1.9.0",
+    "@ata-validator/native-linux-x64-gnu": "1.9.0",
+    "@ata-validator/native-linux-arm64-gnu": "1.9.0",
+    "@ata-validator/native-linux-x64-musl": "1.9.0",
+    "@ata-validator/native-linux-arm64-musl": "1.9.0",
+    "@ata-validator/native-win32-x64": "1.9.0"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"