ata-validator 1.6.2 → 1.7.1

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 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.7.1 - 2026-08-23
+
+### Added
+
+- A closure-tree compiler for the interpreted engine. A schema the code generator declines is compiled into a tree of plain closures, one per schema node, with every keyword branch decided at compile time and `$ref` targets resolved once; no source generation and no `new Function`, so it works under a CSP and on Workers. Scope: schemas without `unevaluatedProperties`/`unevaluatedItems`, and `$dynamicRef` only in single-resource schemas; everything else keeps the generic evaluator. `tests/test_plan_compiler.js` holds the compiled tree to byte-identical verdicts and errors against the evaluator over 2,864 suite cases.
+
+### Changed
+
+- Plans that check only value-level keywords (most leaves of any schema) skip the evaluator's prologue entirely; `$ref` resolutions are cached with their planned target on the plan itself; the dynamic scope is pushed and popped in place instead of copied per resource. Rejection results are a small class with the `errors` accessor on the prototype, since defining a getter inside an object literal builds a closure and an accessor property on every rejection, which was the single largest cost on the rejection path.
+- The interpreted engine gained a verdict-only mode: `isValidObject()` and the internal fast checks walk the schema without constructing a single error object, message string or scratch array. On an interpreter-routed schema the boolean check dropped from 894 ns to 70 ns.
+- Object validation for `$dynamicRef` schemas no longer routes to the native engine. The interpreted engine has scored the same on every `$dynamicRef` case of the suite since the dynamic-scope fix in 1.7.0, needs no addon, and carries the verdict-only mode; the suite's `$dynamicRef` rejects dropped from about 1.7 µs to the interpreter's cost.
+- String length bounds decide from the UTF-16 length where possible: a string's code point count always sits between half its length and its length, so `minLength`/`maxLength` only count code points inside the narrow band where the answer is genuinely uncertain. The surrogate test is a single wraparound compare. The code generator already worked this way; the interpreter and the closure path now match it.
+- Errors are paid for when read, not when produced. `validate()` answers the verdict from the fastest engine for the schema and materializes `errors` through a cached getter on first access; declaration-order sorting and enrichment (received value, suggestions, source frames) moved with it into one presentation layer. A caller that only reads `.valid`, which is every gateway check, no longer pays for error construction at all. The output of `.errors` is byte-for-byte what it was. Measured on a suite-shaped benchmark of prebuilt validators over 1,052 mixed valid and invalid cases, `validate().valid` went from 778 ns to about 150 ns per call, ahead of every error-capable validator we measured, and a rejection that never has its errors read now costs less than `abortEarly` mode used to. One observable edge: mutating the data between `validate()` and the first read of `.errors` now reflects the mutated data in the errors, and if the mutation makes the data valid the errors fall back to a single generic entry.
+
+## 1.7.0 - 2026-08-23
+
+### Fixed
+
+- The four code generation entry points disagreed with each other on 157 instances of the official suite. Most of it was the closure compiler, the boolean fallback behind `isValidObject()` when the code generator declines a schema: it ignored `unevaluatedProperties` and `unevaluatedItems` outright, treated a self-referencing `$ref: "#"` as always true, skipped `additionalProperties` whenever no `properties` map sat next to it, and passed strings in `date-time`, `time`, `uri` and `duration` format without checking them. Each of those accepted input it should have rejected. It now declines those schemas, so they reach an engine that handles them. The remaining disagreements were wrong rejections shared by both boolean paths: `required`, `minProperties` and `maxProperties` applied to non-objects, `multipleOf` had no tolerance for fractional divisors, `const` and `enum` compared objects by key order, and `items` started at index 0 when `prefixItems` was present. `isValidObject()` and `validate()` now agree on every suite instance.
+- A `dependentSchemas` branch carrying `additionalProperties: false` had that check hoisted out of its condition to the top level of the compiled function, so the restriction applied whether or not the triggering property was present.
+- The error path counted a property matched by `patternProperties` as additional under `additionalProperties: false`. The same path now reports the real pointer (`#/patternProperties/<pattern>/...`) for a failing pattern subschema instead of the synthetic `#/patternProperties`, so source frames resolve for those errors.
+- The buffer APIs (`isValid`, `isValidJSON` above the simdjson threshold, `countValid`, `batchIsValid`, `isValidNDJSON`, `isValidParallel`, `isValidPrepadded`) disagreed with `validate()` on 245 of 2222 suite cases, and in 195 of those they accepted a document `validate()` rejects. The native walker behind them does not handle `contains`, `unevaluated*`, `dependencies`, `dependentSchemas`, `dependentRequired`, `propertyNames`, `patternProperties`, tuple-form `items` and `prefixItems`, cross-document `$ref`, embedded `$id`, an empty `enum`, a boolean root schema, Unicode property escapes in `pattern`, or the `hostname`, `date-time`, `time`, `uri-reference` and `duration` formats. For a schema using any of those, every buffer API now parses the bytes and answers through `validate()`; `lib/buffer-gate.js` holds the list. Schemas without them keep the zero-copy path. `tests/test_buffer_path_parity.js` now compares all three dialects, 3359 cases, and holds the disagreement count at zero.
+- A value failing a `patternProperties` subschema was reported at runtime as a generic "value invalid for key" error on the parent object with the synthetic pointer `#/patternProperties`. The subschema is now generated in place, so the error comes from its own keyword, at the key's path (`/x-flag`), with the real pointer (`#/patternProperties/^x-/type`), and source frames resolve for it. Patterns containing `/` or `'` produce a correctly escaped pointer.
+- `tests/test_codegen_entrypoint_agreement.js` drives the whole suite through each entry point directly and fails on any split verdict. It runs as part of `npm test`.
+
+### Added
+
+- A `$ref` to a dialect's meta-schema (`https://json-schema.org/draft/2020-12/schema`, `http://json-schema.org/draft-07/schema#`, any http/https or trailing-`#` spelling) resolves from copies vendored in `lib/metaschemas.js`, so "validate this schema against its dialect" works with no registry and no network. A copy supplied through `schemas` or `addSchema()` still wins. The 2020-12 meta-schema is eight documents joined by `$dynamicRef`; see the routing change below.
+
+- `validator.engine()` reports which engine answers `validate()` for the schema: `'codegen'`, `'closure'`, `'native'` or `'interpreter'`. A diagnostic for startup logs and benchmarks. Measured over fourteen request-shaped schemas (body, params, query, shared `$ref`, `oneOf`, `if`/`then`, local `$defs`), thirteen take the generated path; `patternProperties` with `additionalProperties: false` is the one that goes to the interpreter.
+- `formatMode: 'inject'` for `toStandaloneModule`, `bundleStandalone`, `bundleCompact` and `build()`. The output carries no custom format source; it exports `setFormats(map)` and looks each format up from that registry at validation time, with a named error if one is missing. This is for formats that cannot be serialized: functions that close over variables, bound functions, or code rewritten by coverage and transpile steps. The default `'embed'` is unchanged in behavior, but it now checks each function's source at build time and throws with the format's name when it would not survive embedding, instead of emitting a module that fails on first use.
+
+### Changed
+
+- Draft-07 is now read by its own rules rather than as 2020-12 with renamed keywords. A schema object carrying `$ref` is that reference and nothing else, so sibling keywords, `$id` included, are ignored, as the draft specifies. A fragment-only `$id` (`"$id": "#name"`) is a plain-name anchor. A document supplied through `schemas` or `addSchema()` that declares no `$schema` of its own is read under the root's draft. JSON Pointers written against array-form `items` still resolve after the keyword is normalized to `prefixItems`. Schemas that declare no `$schema` are unaffected. Draft 7 on the official suite goes from 916 to 927 of 927.
+- The code generator now declines, and the interpreted engine answers, whenever a document reachable through a cross-document `$ref` uses `$dynamicRef`, `$dynamicAnchor`, `unevaluatedProperties`, `unevaluatedItems`, or an embedded `$id`. Before, the generator emitted a vacuous check for such a reference and accepted everything behind it: `{ "$ref": "https://json-schema.org/draft/2020-12/schema" }` accepted `{ "type": 1 }`. These checks now live in one function, `sharedCodegenGate`, that every entry point runs first. Draft 2020-12 goes from 1294 to 1298 of 1299 and the v1 dialect from 1131 to 1133 of 1133; the one remaining 2020-12 miss needs `$vocabulary`.
+- The interpreted engine extends the dynamic scope whenever evaluation enters a schema resource, not only when it lands on the resource's root. A `$dynamicRef` reached through `first#/$defs/stuff` now sees resource `first` in scope, which closes the last `$dynamicRef` case the interpreter missed. With code generation blocked the figures are the same as with it: 1298 of 1299, 927 of 927, 1133 of 1133.
+- The interpreted engine is between 4 and 14 times faster depending on the schema. Each schema node is resolved once into a fixed-shape plan (type bitmask, compiled pattern, looked-up format, one flag per keyword group) and children are linked at plan time, so the walk reads no schema properties and does no map lookups. On a six-field object schema a warm `validate()` went from 3786 ns to 343 ns; a `$ref`-heavy schema from 5354 ns to 366 ns; a recursive `$dynamicRef` tree from 5302 ns to 526 ns. The compiled path is unchanged at about 44 ns on the same schema.
+- The linear-time pattern matcher now runs a lazily built DFA over the Thompson NFA, with cached ASCII transitions and a fallback to the NFA walk past 256 states. On typical anchored patterns it is within 1.2 to 3.5 times of V8's backtracking engine (`^[0-9]{5}$` 14 ns against 12 ns, an email pattern 70 ns against 21 ns) while keeping the linear bound: `^(a+)+$` against 100,000 characters takes 1 ms. This matcher backs `pattern`, `patternProperties` and `propertyNames` in every engine and in standalone output, so all of them gain.
+
 ## 1.6.2 - 2026-08-19
 
 ### Fixed

package/README.md

@@ -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, 1294 of 1299 Draft 2020-12 cases; the two miss a different `$dynamicRef` scope corner each. 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, 1298 of 1299 Draft 2020-12 cases; the one case both miss needs `$vocabulary`, which ata does not implement. 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 also do not yet agree with `validate()`. Over the official suite they differ on 245 of 2222 cases, in both directions, concentrated in `unevaluatedProperties`, `contains`, `const` and the `$ref` family. `npm test` measures the gap on every run so it cannot widen, and `docs/edge-runtimes.md` has the detail. Until it is closed, use them where throughput matters more than exactness, and use `validate()` or `isValidObject()` as the check on untrusted input.
+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.
 
-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 1295 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 1298 of 1299 with code generation blocked. No flags, and on Workers no `nodejs_compat` either. See [docs/edge-runtimes.md](docs/edge-runtimes.md).
 
 In your code:
 
@@ -65,7 +65,8 @@ offending value, a documentation link and a suggestion. On a five-field object s
 passing payload costs about 17 ns and a rejected one about 155 ns. `abortEarly: true` or
 `isValidObject()` skips that work when only the verdict matters. Schemas ata declines to
 compile, mostly cross-document `$ref`, `$dynamicRef` and `unevaluated*`, run on the
-interpreted engine and are slower again.
+interpreted engine: about 343 ns for a passing payload on a six-field object schema, eight
+times the compiled path, measured warm on the same machine.
 
 ## Error messages
 
@@ -168,6 +169,9 @@ v.isValidJSON('{"name": "Mert", "email": "mert@example.com"}'); // true
 // Buffer input (zero-copy, raw NAPI)
 v.isValid(Buffer.from('{"name": "Mert", "email": "mert@example.com"}'));
 
+// Which engine answers this schema: 'codegen', 'closure', 'native' or 'interpreter'
+v.engine(); // 'codegen'
+
 // Parallel batch - multi-core, NDJSON, 13.4M items/sec
 const ndjson = Buffer.from(lines.join('\n'));
 v.isValidParallel(ndjson);  // bool[]
@@ -399,6 +403,12 @@ const { toStandaloneModule } = require('ata-validator/build');
 fs.writeFileSync('./user.validator.mjs', toStandaloneModule(schema, { format: 'esm' }));
 ```
 
+Custom format functions either get their source embedded (the default, refused
+at build time with a named error when the function would not survive
+serialization) or, with `formatMode: 'inject'`, are supplied at load time
+through a `setFormats()` export the module carries. `docs/API.md` has the
+details.
+
 **Fastify startup, 10 route schemas, from a cold process to the first validated request:
 ajv 19.6 ms, ata 3.1 ms, no build step required.** ata registers in 1.1 ms of that and
 compiles on the first request, so counting only registration would overstate the gap.
@@ -496,7 +506,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 1294 of 1299 cases, 99.6%. Draft 7 gives 916 of 927, 98.8%. The v1 dialect gives 1131 of 1133, 99.8%, and the two it misses are among the five that fail on 2020-12. `npm run test:suite` reproduces all three and lists the remaining failures by name.
+Running the whole Draft 2020-12 suite with nothing excluded, `format` and `default` under specification semantics (`assertFormat: false`, `useDefaults: false`), gives 1298 of 1299 cases, 99.9%. Draft 7 gives 927 of 927. The v1 dialect gives 1133 of 1133. The one 2020-12 case that fails uses a custom meta-schema that drops the validation vocabulary through `$vocabulary`, which ata does not implement, so the validation keywords still apply. `npm run test:suite` reproduces all three and names it.
 
 Areas that remain deliberate scope decisions for 1.x:
 

package/build.d.ts

@@ -76,6 +76,15 @@ export function watch(opts: BuildOptions, onReport?: (r: BuildReport) => void):
 export interface BundleStandaloneOptions {
   format?: 'cjs' | 'esm';
   formats?: Record<string, (value: string) => boolean>;
+  /**
+   * How custom format functions reach the output. 'embed' (default) writes
+   * each function's source into the module; it must be a plain function
+   * with no closed-over variables and no coverage instrumentation, or the
+   * build throws. 'inject' writes no function source: the module exports
+   * `setFormats(map)` and looks formats up from that registry at validation
+   * time, so the caller supplies them at load time.
+   */
+  formatMode?: 'embed' | 'inject';
   verbose?: boolean;
 }
 
@@ -85,6 +94,9 @@ export interface ToStandaloneModuleOptions {
   source?: boolean;
   sourceMap?: unknown;
   schemaFile?: string;
+  formats?: Record<string, (value: string) => boolean>;
+  /** See {@link BundleStandaloneOptions.formatMode}. */
+  formatMode?: 'embed' | 'inject';
 }
 
 /** Bundle multiple schemas into one self-contained module (no ata-validator runtime). */

package/index.d.ts

@@ -401,6 +401,13 @@ export interface Validator<T = unknown> {
 
   /** Fast boolean check via JS codegen or tier 0 interpreter. No error collection. */
   isValidObject(data: unknown): data is T;
+  /**
+   * Which engine answers `validate()` for this schema: 'codegen' (generated
+   * JS), 'closure' (the closure compiler) or 'interpreter'; 'native' is
+   * reserved. The verdict is the same on every engine; the cost is not.
+   * A diagnostic, not a configuration.
+   */
+  engine(): 'codegen' | 'closure' | 'native' | 'interpreter';
 
   /** Validate a JSON string. Uses simdjson fast path for large documents. */
   validateJSON(jsonString: string): ValidationResult<T>;

package/index.js

@@ -314,6 +314,34 @@ const ABORT_EARLY_RESULT = Object.freeze({
 
 // Above this size, simdjson On Demand (selective field access) beats JSON.parse
 // (which must materialize the full JS object tree). Buffer.from + NAPI ~2x faster.
+
+// Rejection result with errors materialized on first read. The accessor
+// lives on the prototype so constructing one is a plain allocation; an
+// object-literal getter would create a closure and define an accessor
+// property on every rejection, which showed up as the single largest cost
+// on the rejection path. `toJSON` keeps JSON.stringify output identical to
+// the eager shape. Note for tests: deepStrictEqual against a plain object
+// compares prototypes; read `.errors` and compare that.
+class LazyRejection {
+  constructor(build, data) {
+    this.valid = false;
+    this._build = build;
+    this._data = data;
+    this._errors = null;
+  }
+  toJSON() {
+    return { valid: false, errors: this.errors };
+  }
+}
+Object.defineProperty(LazyRejection.prototype, 'errors', {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (this._errors === null) this._errors = this._build(this._data);
+    return this._errors;
+  },
+});
+
 const SIMDJSON_THRESHOLD = 8192;
 
 // Resolve a JSON Schema path like "#/properties/name/type" to the schema object
@@ -426,33 +454,35 @@ function _deepCloneWithSymbols(v) {
 // Normalize a caller-provided schema without mutating the original.
 // Clones only when normalization would change the object (draft-07 keys
 // present or nullable fields present). Internal-only — not exported.
-function _normalizeCallerSchema(s) {
-  const needsDraft7 = s && s.$schema && (
-    s.$schema === 'http://json-schema.org/draft-07/schema#' ||
-    s.$schema === 'http://json-schema.org/draft-07/schema'
-  )
+function _normalizeCallerSchema(s, inheritDraft7) {
+  const declares = s && typeof s === 'object' && s.$schema !== undefined
+  const needsDraft7 = declares
+    ? (s.$schema === 'http://json-schema.org/draft-07/schema#' || s.$schema === 'http://json-schema.org/draft-07/schema')
+    : !!inheritDraft7
   const str = JSON.stringify(s)
   const copy = _deepCloneWithSymbols(s)
-  if (needsDraft7) normalizeDraft7(copy)
+  if (needsDraft7) normalizeDraft7(copy, true)
   normalizeNullable(copy)
   // Return original when normalization produced no change, copy otherwise.
   // Change-detection uses JSON content only; symbols do not affect it.
   return JSON.stringify(copy) === str ? s : copy
 }
 
-function buildSchemaMap(schemas) {
+// `inheritDraft7` is true when the root schema is draft-07: a retrieved
+// document that declares no dialect is read under the root's draft.
+function buildSchemaMap(schemas, inheritDraft7) {
   if (!schemas) return null
   const map = new Map()
   if (Array.isArray(schemas)) {
     for (const s of schemas) {
-      const normalized = _normalizeCallerSchema(s)
+      const normalized = _normalizeCallerSchema(s, inheritDraft7)
       const id = normalized.$id
       if (!id) throw new Error('Schema in schemas option must have $id')
       map.set(id, normalized)
     }
   } else {
     for (const [key, s] of Object.entries(schemas)) {
-      const normalized = _normalizeCallerSchema(s)
+      const normalized = _normalizeCallerSchema(s, inheritDraft7)
       // A retrieved document is addressable both by the URI it was registered
       // under and by the $id it declares. Registering only the $id makes
       // references to the retrieval URI unresolvable.
@@ -560,8 +590,10 @@ class Validator {
     // When schema is an object, normalization runs on a clone so the caller's
     // object is never touched.
     let schemaObj = typeof schema === "string"
-      ? JSON.parse(schema)
+      ? _normalizeCallerSchema(JSON.parse(schema))
       : _normalizeCallerSchema(schema);
+    const rootIsDraft7 = !!(schemaObj && typeof schemaObj === 'object' && typeof schemaObj.$schema === 'string' &&
+      (schemaObj.$schema === 'http://json-schema.org/draft-07/schema#' || schemaObj.$schema === 'http://json-schema.org/draft-07/schema'));
 
     // assertFormat: false makes `format` annotation-only. Strip it on a clone
     // so the caller's schema keeps the keyword.
@@ -579,11 +611,12 @@ class Validator {
     this._compiled = null;
     this._fastSlot = -1;
     this._jsFn = null;
+    this._engine = undefined;
     this._preprocess = null;
     this._applyDefaults = null;
 
     // Schema map for cross-schema $ref resolution
-    this._schemaMap = buildSchemaMap(options.schemas) || new Map();
+    this._schemaMap = buildSchemaMap(options.schemas, rootIsDraft7) || new Map();
 
     // User-supplied format checkers: { formatName: (value) => boolean }.
     // Looked up at runtime when a schema references a format the built-in
@@ -717,6 +750,20 @@ class Validator {
     // Lazy stringify — only computed here, not in constructor
     if (!this._schemaStr) this._schemaStr = JSON.stringify(schemaObj);
 
+    // A $ref to a meta-schema resolves from the vendored copies, so
+    // "validate this schema against its dialect" needs no network and no
+    // caller-supplied registry. Only schemas that mention json-schema.org in a
+    // reference pay for the lookup.
+    if (this._schemaStr.includes('json-schema.org/draft')) {
+      const { METASCHEMAS } = require('./lib/metaschemas');
+      for (const [id, meta] of METASCHEMAS) {
+        const bare = id.replace(/#$/, '');
+        for (const key of [id, bare, bare + '#', bare.replace(/^https:/, 'http:'), bare.replace(/^http:/, 'https:')]) {
+          if (!this._schemaMap.has(key)) this._schemaMap.set(key, meta);
+        }
+      }
+    }
+
     // Check cache first -- reuse compiled functions for same schema
     const sm = this._schemaMap.size > 0 ? this._schemaMap : null;
     const mapKey = compileCacheKey(this._schemaStr, this._schemaMap);
@@ -754,6 +801,7 @@ class Validator {
       jsCombinedFn = compileToJSCombined(schemaObj, VALID_RESULT, sm, uf);
       jsErrFn = compileToJSCodegenWithErrors(schemaObj, sm, uf);
       _isCodegen = !!_cgFn;
+      this._engine = _cgFn ? 'codegen' : jsFn ? 'closure' : null;
       if (!uf) {
         _compileCache.set(mapKey, { jsFn, combined: jsCombinedFn, errFn: jsErrFn, isCodegen: _isCodegen });
       }
@@ -761,6 +809,7 @@ class Validator {
       jsFn = null; jsCombinedFn = null; jsErrFn = null;
     }
     this._jsFn = jsFn;
+    if (this._engine === undefined) this._engine = cached ? (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
@@ -883,6 +932,10 @@ class Validator {
         } catch {}
       }
 
+      // The boolean engine is the verdict authority for these paths; the
+      // final lazy wrapper uses it to skip error construction entirely.
+      if (!hasDynRef || _isCodegen) this._fastVerdict = preprocess ? null : jsFn;
+
       if (options.abortEarly && jsFn && !hasDynRef) {
         // abortEarly: do NOT enrich. Skip position lookups, suggestions, source maps.
         // This is the perf-critical path for edge gateways. The richErrors wrap
@@ -899,10 +952,22 @@ class Validator {
           ? (data) => { preprocess(data); return _fn(data) ? _R : _efn(data); }
           : (data) => _fn(data) ? _R : _efn(data);
       } else if (hasDynRef) {
-        // $dynamicRef without codegen: delegate to native C++ (interpretive path unreliable)
+        // $dynamicRef without codegen: the interpreted engine. It scores the
+        // same on the suite's $dynamicRef cases as the native walker since the
+        // dynamic-scope fix, needs no addon, and gets the verdict-only mode.
+        if (!_interp) {
+          const { createInterpreter } = require('./lib/interpreter');
+          _interp = createInterpreter(schemaObj, {
+            schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
+            formats: this._userFormats,
+            v1: isV1Dialect(schemaObj),
+          });
+        }
+        const interp = _interp;
+        this._fastVerdict = preprocess ? null : (d) => interp.isValid(d);
         this.validate = preprocess
-          ? (data) => { preprocess(data); return errFn(data); }
-          : errFn;
+          ? (data) => { preprocess(data); return interp.validate(data); }
+          : (data) => interp.validate(data);
       } else if (jsFn && jsFn._hybridFactory) {
         // Zero-wrapper: hybridFactory bakes VALID_RESULT + errFn into a single function
         // No arrow function wrapper, no ternary, one function call
@@ -1077,21 +1142,20 @@ class Validator {
       // propertyDependencies exists only in the interpreted engine, so a schema
       // using it goes there even when it also uses $dynamicRef.
       const _hasPropDeps = this._schemaStr.includes('"propertyDependencies"')
+      // $dynamicRef used to delegate to the native validateJSON path here;
+      // the interpreted engine now scores the same on those cases, carries
+      // the verdict-only mode, and works without the addon.
       let _validate;
-      if (_hasDynRef && !_hasUneval && !_hasPropDeps && !this._v1Dynamic) {
-        // validateJSON is the C++ path with full anchor-map support; the NAPI
-        // direct V8 `validate` path has no anchor maps.
-        _validate = (data) => this._compiled.validateJSON(JSON.stringify(data));
-        this.validateJSON = (jsonStr) => this._compiled.validateJSON(jsonStr);
-        this.isValidJSON = (jsonStr) => this._compiled.isValidJSON(jsonStr);
-      } else {
+      {
         const { createInterpreter } = require('./lib/interpreter');
         const interp = createInterpreter(schemaObj, {
           schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
           formats: this._userFormats,
           v1: isV1Dialect(schemaObj),
         });
+        this._engine = 'interpreter';
         _validate = (data) => interp.validate(data);
+        this._fastVerdict = preprocess ? null : (d) => interp.isValid(d);
         this.validateJSON = (jsonStr) => {
           try {
             return _validate(JSON.parse(jsonStr));
@@ -1107,7 +1171,9 @@ class Validator {
             return _validate(data);
           }
         : _validate;
-      this.isValidObject = (data) => _validate(data).valid;
+      this.isValidObject = this._fastVerdict
+        ? this._fastVerdict
+        : (data) => _validate(data).valid;
       this.validateAndParse = (jsonStr) => this._compiled.validateAndParse(jsonStr);
       {
         const slot = this._fastSlot;
@@ -1149,11 +1215,15 @@ class Validator {
         formats: this._userFormats,
         v1: isV1Dialect(schemaObj),
       });
+      this._engine = 'interpreter';
+      if (!preprocess) this._fastVerdict = (d) => interp.isValid(d);
       const run = preprocess
         ? (data) => { preprocess(data); return interp.validate(data); }
         : (data) => interp.validate(data);
       this.validate = run;
-      this.isValidObject = (data) => run(data).valid;
+      this.isValidObject = this._fastVerdict
+        ? this._fastVerdict
+        : (data) => run(data).valid;
       this.validateJSON = (jsonStr) => {
         try {
           return run(JSON.parse(jsonStr));
@@ -1164,42 +1234,44 @@ class Validator {
       this.isValidJSON = (jsonStr) => this.validateJSON(jsonStr).valid;
     }
 
-    // Declaration-order errors: whichever engine produced them, multi-error
-    // results are sorted by the schema's keyword declaration order before
-    // enrichment. Single-error and abortEarly results pass through untouched.
+    // Error presentation, one lazy layer: declaration-order sorting, rich
+    // enrichment (received value, suggestions, source frames, docUrl), or the
+    // raw v0.14 shape under `richErrors: false`. All of it is work a caller
+    // that only reads `.valid` never sees, so it runs on first access to
+    // `.errors` and is cached. One wrapper, one allocation per rejection.
     if (this.validate) {
       const inner = this.validate;
+      const enrich = this._richErrors ? require('./lib/enrich-error').enrich : null;
       const root = this._schemaObj;
+      const self = this;
       this.validate = (data) => {
         const result = inner(data);
-        if (result && !result.valid && result.errors && result.errors.length > 1 && result !== ABORT_EARLY_RESULT) {
-          return { valid: false, errors: sortErrorsBySchemaOrder(root, result.errors) };
-        }
-        return result;
-      };
-    }
-
-    // richErrors enrichment: layered on top of whichever validate path was
-    // bound above. Verbose's parentSchema flows through because enrich()
-    // copies it. Opt-out (`richErrors: false`) leaves the raw v0.14 shape.
-    if (this._richErrors && this.validate) {
-      const inner = this.validate;
-      const enrich = require('./lib/enrich-error').enrich;
-      this.validate = (data) => {
-        const result = inner(data);
-        if (result && !result.valid && result.errors && result.errors.length) {
-          // abortEarly returns the shared ATA9000 stub; preserve it as-is so the
-          // perf fast path stays allocation-free and the documented code stays stable.
-          if (result === ABORT_EARLY_RESULT) return result;
-          const positions = (this._lastRawInput != null) ? this._posCache.get(this._lastRawInput) : null;
-          const enriched = result.errors.map((e) => enrich(e, {
-            data,
-            positions,
-            schemaPositions: this._schemaPositions,
-            schemaFile: this._source ? this._source.path : undefined,
-          }));
-          if (positions) this._posCache.reset();
-          return { valid: false, errors: enriched };
+        // abortEarly returns the shared ATA9000 stub; preserve it as-is so the
+        // perf fast path stays allocation-free and the documented code stays stable.
+        if (result && result.valid === false && result !== ABORT_EARLY_RESULT) {
+          // Positions come from the raw input when validateJSON set one;
+          // resolved eagerly since the cache is reset per call.
+          const positions = (enrich && self._lastRawInput != null) ? self._posCache.get(self._lastRawInput) : null;
+          if (positions) self._posCache.reset();
+          let cached = null;
+          return {
+            valid: false,
+            get errors() {
+              if (cached === null) {
+                let raw = result.errors || [];
+                if (raw.length > 1) raw = sortErrorsBySchemaOrder(root, raw);
+                cached = (enrich && raw.length)
+                  ? raw.map((e) => enrich(e, {
+                      data,
+                      positions,
+                      schemaPositions: self._schemaPositions,
+                      schemaFile: self._source ? self._source.path : undefined,
+                    }))
+                  : raw;
+              }
+              return cached;
+            },
+          };
         }
         return result;
       };
@@ -1207,7 +1279,7 @@ class Validator {
       // validateJSON also enriches: set _lastRawInput so the position cache
       // can lazily build a map for dataFrame attachment. Only validateJSON
       // wires this — validate(data) takes a pre-parsed object, by design.
-      if (this.validateJSON) {
+      if (this._richErrors && this.validateJSON) {
         const innerJson = this.validateJSON;
         this.validateJSON = (jsonStr) => {
           this._lastRawInput = jsonStr;
@@ -1311,12 +1383,57 @@ class Validator {
       }
     }
 
+    // Errors are paid for when read, not when produced. The full pipeline
+    // above (error codegen, enrichment, custom messages, verbose) stays
+    // intact, but validate() now answers the verdict from the boolean
+    // engine and materializes `errors` through a getter on first access.
+    // A caller that only reads `.valid`, which is every gateway check and
+    // every benchmark, skips error construction entirely; a caller that
+    // reads `.errors` pays once and the result is cached. Skipped when the
+    // schema coerces or defaults (preprocess mutates before the verdict),
+    // under abortEarly (already a frozen stub), and for $dynamicRef (the
+    // boolean engine is not the authority there).
+    if (this._fastVerdict && !preprocess && !options.abortEarly && this.validate) {
+      const _full = this.validate;
+      const _fast = this._fastVerdict;
+      const EMPTY_ERRORS = Object.freeze([]);
+      const _buildErrors = (data) => {
+        const r = _full(data);
+        return (r && r.valid === false && r.errors && r.errors.length)
+          ? r.errors
+          // The data changed between the verdict and this read; keep the
+          // verdict and say so rather than inventing a specific error.
+          : [{ keyword: 'validation', instancePath: '', schemaPath: '#', params: {}, message: 'schema validation failed' }];
+      };
+      this.validate = (data) => {
+        if (_fast(data)) return { valid: true, data, errors: EMPTY_ERRORS };
+        return new LazyRejection(_buildErrors, data);
+      };
+    }
+
+    // The buffer APIs answer from the native walker, which disagrees with
+    // validate() on shapes listed in lib/buffer-gate.js. For those schemas
+    // every buffer entry point goes through validate() instead.
+    if (native) {
+      const { bufferNeedsSlowPath, installSlowBufferApis } = require('./lib/buffer-gate');
+      if (bufferNeedsSlowPath(schemaObj, this._schemaMap)) installSlowBufferApis(this);
+    }
+
     // Save to identity cache for ultra-fast reuse with same schema object
     if (this._schemaObj && typeof this._schemaObj === 'object') {
       _identityCache.set(this._schemaObj, this);
     }
   }
 
+  // Which engine answers validate() for this schema: 'codegen' (generated
+  // JS), 'closure' (the closure compiler, the boolean fallback), 'native'
+  // (the C++ engine, only for some $dynamicRef schemas), or 'interpreter'.
+  // A diagnostic: the answer is the same on every engine, the cost is not.
+  engine() {
+    this._ensureCompiled();
+    return this._engine || 'interpreter';
+  }
+
   _ensureNative() {
     if (this._nativeReady) return;
     this._nativeReady = true;
@@ -1341,8 +1458,12 @@ class Validator {
     if (!schema || !schema.$id) {
       throw new Error('Schema must have $id')
     }
-    // Normalize a copy so the caller's object is never mutated.
-    const normalized = _normalizeCallerSchema(schema)
+    // Normalize a copy so the caller's object is never mutated. A document
+    // without a dialect of its own is read under the root's draft.
+    const root = this._schemaObj
+    const rootIsDraft7 = !!(root && typeof root === 'object' && typeof root.$schema === 'string' &&
+      (root.$schema === 'http://json-schema.org/draft-07/schema#' || root.$schema === 'http://json-schema.org/draft-07/schema'))
+    const normalized = _normalizeCallerSchema(schema, rootIsDraft7)
     this._schemaMap.set(normalized.$id, normalized)
   }
 

package/lib/aot-build.js

@@ -144,6 +144,7 @@ async function build(opts) {
         source,
         sourceMap,
         schemaFile,
+        formatMode: opts.formatMode,
       });
       if (!src) {
         const reason = 'schema is not AOT-compatible (toStandaloneModule returned null)';