ata-validator 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 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.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
 
@@ -496,7 +497,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), 'native' (the C++ engine, only
+   * for some $dynamicRef schemas) or 'interpreter'. 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

@@ -426,33 +426,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 +562,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 +583,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 +722,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 +773,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 +781,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
@@ -1081,6 +1102,7 @@ class Validator {
       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.
+        this._engine = 'native';
         _validate = (data) => this._compiled.validateJSON(JSON.stringify(data));
         this.validateJSON = (jsonStr) => this._compiled.validateJSON(jsonStr);
         this.isValidJSON = (jsonStr) => this._compiled.isValidJSON(jsonStr);
@@ -1091,6 +1113,7 @@ class Validator {
           formats: this._userFormats,
           v1: isV1Dialect(schemaObj),
         });
+        this._engine = 'interpreter';
         _validate = (data) => interp.validate(data);
         this.validateJSON = (jsonStr) => {
           try {
@@ -1149,6 +1172,7 @@ class Validator {
         formats: this._userFormats,
         v1: isV1Dialect(schemaObj),
       });
+      this._engine = 'interpreter';
       const run = preprocess
         ? (data) => { preprocess(data); return interp.validate(data); }
         : (data) => interp.validate(data);
@@ -1311,12 +1335,29 @@ class Validator {
       }
     }
 
+    // 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 +1382,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)';

package/lib/aot.js

@@ -98,6 +98,48 @@ module.exports = { boolFn, hybridFactory, errFn };
 //
 // format: 'esm' | 'cjs'. Default 'esm'.
 // abortEarly: if true, invalid result is a shared stub; smaller output.
+
+// Custom format functions in standalone output.
+//
+// 'embed' (default) writes each function's source into the module through
+// Function#toString. That only works for a plain function: one that closes
+// over nothing and is not rewritten by a coverage or transpile step (istanbul
+// injects `cov_` counters; a bundler may hoist helpers). The check below
+// rejects those at build time with a named error instead of emitting a module
+// that throws on first use.
+//
+// 'inject' writes no function source. The module exports `setFormats(map)`
+// and each format is looked up from that registry when a value is checked,
+// so the caller supplies the functions at load time.
+function emitFormatDecls(closures, mode, declKW) {
+  if (!closures || closures.length === 0) return { decls: '', exportsSetFormats: false };
+  if (mode === 'inject') {
+    let out = `${declKW} __formats = Object.create(null);\n`;
+    out += `function setFormats(map) { for (const k in map) __formats[k] = map[k]; }\n`;
+    for (const { name, format } of closures) {
+      const key = JSON.stringify(format === null ? name.slice(4) : format);
+      out += `${declKW} ${name} = function (v) { const f = __formats[${key}]; if (typeof f !== 'function') throw new Error('ata: format ' + ${key} + ' is not registered; call setFormats({ [' + ${key} + ']: fn }) before validating'); return f(v); };\n`;
+    }
+    return { decls: out, exportsSetFormats: true };
+  }
+  let out = '';
+  for (const { name, fn, format } of closures) {
+    const src = fn.toString();
+    const label = format === null ? name : format;
+    if (/\bcov_[A-Za-z0-9_$]+\b/.test(src)) {
+      throw new Error(`ata: custom format "${label}" is instrumented for coverage and cannot be embedded; use { formatMode: 'inject' } and register it with setFormats() at load time`);
+    }
+    try {
+      // eslint-disable-next-line no-new-func
+      new Function('return (' + src + ')');
+    } catch {
+      throw new Error(`ata: custom format "${label}" has no standalone source (a bound function, a class method, or a native); use { formatMode: 'inject' } and register it with setFormats() at load time`);
+    }
+    out += `${declKW} ${name} = ${src};\n`;
+  }
+  return { decls: out, exportsSetFormats: false };
+}
+
 function toStandaloneModule(validator, opts) {
   validator._ensureCompiled();
   const jsFn = validator._jsFn;
@@ -170,20 +212,17 @@ function toStandaloneModule(validator, opts) {
   // User-supplied format functions are referenced as _uf_<name> by both the
   // boolean (_fn) and error (errFn) bodies. Embed them via Function#toString
   // so the standalone module stays self-contained.
-  let formatDecls = '';
-  if (jsFn._formatClosures && jsFn._formatClosures.length > 0) {
-    formatDecls = jsFn._formatClosures
-      .map(({ name, fn }) => `const ${name} = ${fn.toString()};`)
-      .join('\n') + '\n';
-  }
+  const fmt = emitFormatDecls(jsFn._formatClosures, opts && opts.formatMode, 'const');
+  const formatDecls = fmt.decls;
 
   const validBody = errCore
     ? 'return _fn(data) ? VALID : { valid: false, errors: errFn(data, true).errors }'
     : 'return _fn(data) ? VALID : ABORT';
 
+  const names = fmt.exportsSetFormats ? 'validate, isValid, setFormats' : 'validate, isValid';
   const exports = format === 'esm'
-    ? `export { validate, isValid };\nexport default { validate, isValid };\n`
-    : `module.exports = { validate, isValid };\nmodule.exports.default = module.exports;\n`;
+    ? `export { ${names} };\nexport default { ${names} };\n`
+    : `module.exports = { ${names} };\nmodule.exports.default = module.exports;\n`;
 
   return `// Auto-generated by ata-validator — do not edit.
 // Schema is embedded; runtime has zero dependency on ata-validator.
@@ -240,6 +279,7 @@ function bundleStandalone(Validator, schemas, opts) {
   const format = (opts && opts.format) || 'cjs';
   const R = 'Object.freeze({valid:true,errors:Object.freeze([])})';
   let bundleUsesSafeRe = false;
+  let bundleInjects = false;
   const fns = schemas.map((schema) => {
     const v = new Validator(schema, bundleOpts);
     v._ensureCompiled();
@@ -255,12 +295,13 @@ function bundleStandalone(Validator, schemas, opts) {
       jsErrFn && jsErrFn._errSource
         ? jsErrFn._errSource
         : "return{valid:false,errors:[{code:'error',path:'',message:'validation failed'}]}";
-    // Serialize custom format closures so the bundle has no runtime dep on ata.
+    // Custom format closures: embedded, or bound to the bundle-level
+    // registry when opts.formats is 'inject'.
     let preamble = '';
     if (jsFn._formatClosures) {
-      preamble = jsFn._formatClosures
-        .map(({ name, fn }) => `var ${name}=${fn.toString()};`)
-        .join('\n');
+      const f = emitFormatDecls(jsFn._formatClosures, opts && opts.formatMode, 'var');
+      preamble = f.decls.replace(/^var __formats = [^\n]*\n|^function setFormats[^\n]*\n/gm, '');
+      if (f.exportsSetFormats) bundleInjects = true;
     }
     // Include hoisted anyOf/oneOf branch helpers (e.g. `_af1_b0`) so the
     // bundle output is self-contained. `toStandalone` emits this same source
@@ -277,10 +318,15 @@ function bundleStandalone(Validator, schemas, opts) {
   });
   const arr = `[${fns.join(',')}]`;
   const safeEmbed = bundleUsesSafeRe ? getSafeRegexEmbed() + '\n' : '';
+  const registry = bundleInjects
+    ? `var __formats=Object.create(null);\nfunction setFormats(map){for(var k in map)__formats[k]=map[k]}\n`
+    : '';
   if (format === 'esm') {
-    return `// Auto-generated by ata-validator — do not edit\n${safeEmbed}const R=${R};\nconst validators=${arr};\nexport default validators;\nexport { validators };\n`;
+    const extra = bundleInjects ? 'export { validators, setFormats };' : 'export { validators };';
+    return `// Auto-generated by ata-validator — do not edit\n${safeEmbed}${registry}const R=${R};\nconst validators=${arr};\nexport default validators;\n${extra}\n`;
   }
-  return `'use strict';\n${safeEmbed}var R=${R};\nmodule.exports=[${fns.join(',')}];\n`;
+  const attach = bundleInjects ? 'module.exports.setFormats=setFormats;\n' : '';
+  return `'use strict';\n${safeEmbed}${registry}var R=${R};\nmodule.exports=[${fns.join(',')}];\n${attach}`;
 }
 
 // Compact bundle: deduplicated code. Shared template functions + per-schema params.
@@ -355,14 +401,17 @@ function bundleCompact(Validator, schemas, opts) {
   // bodies. Collect them across all schemas (deduped by name) and embed via
   // Function#toString so the bundle stays self-contained.
   const fmtSeen = new Set();
+  const fmtAll = [];
   for (const e of entries) {
     if (!e || !e.fmt) continue;
-    for (const { name, fn } of e.fmt) {
-      if (fmtSeen.has(name)) continue;
-      fmtSeen.add(name);
-      out += `${declKW} ${name}=${fn.toString()};\n`;
+    for (const entry of e.fmt) {
+      if (fmtSeen.has(entry.name)) continue;
+      fmtSeen.add(entry.name);
+      fmtAll.push(entry);
     }
   }
+  const fmtOut = emitFormatDecls(fmtAll, opts && opts.formatMode, declKW);
+  out += fmtOut.decls;
 
   // Shared hybrid factories
   out += `${declKW} H=[\n`;
@@ -385,9 +434,10 @@ function bundleCompact(Validator, schemas, opts) {
     })
     .join(',');
   if (isEsm) {
-    out += `const validators=[${arrBody}];\nexport default validators;\nexport { validators };\n`;
+    out += `const validators=[${arrBody}];\nexport default validators;\nexport { validators${fmtOut.exportsSetFormats ? ', setFormats' : ''} };\n`;
   } else {
     out += `module.exports=[${arrBody}];\n`;
+    if (fmtOut.exportsSetFormats) out += 'module.exports.setFormats=setFormats;\n';
   }
 
   return out;

package/lib/buffer-gate.js

@@ -0,0 +1,132 @@
+'use strict';
+
+// The buffer APIs (isValid, countValid, batchIsValid, isValidNDJSON,
+// isValidParallel, isValidPrepadded, and isValidJSON above the simdjson
+// threshold) answer from the native engine's own walker, which is not the
+// engine validate() uses. Measured over the official suite, the two disagreed
+// on 245 of 2222 cases, and 195 of those were the native walker accepting a
+// document validate() rejects. A buffer API that is faster and sometimes
+// wrong in the accepting direction is not a fast path, it is a hole.
+//
+// This module decides, once per schema, whether the native walker can be
+// trusted for it. When it cannot, the buffer APIs are replaced with versions
+// that parse the bytes and call validate(), so every entry point gives the
+// same verdict. The list below is the set of shapes where the suite showed
+// the walker disagreeing, each with the reason. It is deliberately a list of
+// shapes rather than a count: a new disagreement is a new entry here, with
+// tests/test_buffer_path_parity.js holding the total at zero.
+
+// Keywords the native walker does not implement, or implements differently
+// enough to disagree on the suite.
+const UNSUPPORTED_KEYWORDS = new Set([
+  'contains', 'minContains', 'maxContains',
+  'unevaluatedProperties', 'unevaluatedItems',
+  'dependencies', 'dependentSchemas', 'dependentRequired',
+  'propertyNames', 'patternProperties',
+]);
+
+// Formats the native checkers answer differently from the JS ones.
+const DIVERGENT_FORMATS = new Set(['hostname', 'date-time', 'time', 'uri-reference', 'duration']);
+
+const SUBSCHEMA_MAPS = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas', 'dependencies'];
+const SUBSCHEMA_NODES = [
+  'items', 'additionalItems', 'additionalProperties', 'contains', 'propertyNames', 'not',
+  'if', 'then', 'else', 'unevaluatedProperties', 'unevaluatedItems',
+  'allOf', 'anyOf', 'oneOf', 'prefixItems',
+];
+
+function walk(schema, depth) {
+  if (schema === true || schema === false) {
+    // A boolean root is answered wrong by the walker; nested booleans are
+    // handled where they appear (items and prefixItems below).
+    return depth === 0;
+  }
+  if (schema === null || typeof schema !== 'object') return false;
+  if (Array.isArray(schema)) {
+    for (const s of schema) if (walk(s, depth + 1)) return true;
+    return false;
+  }
+  for (const key of Object.keys(schema)) {
+    const v = schema[key];
+    if (UNSUPPORTED_KEYWORDS.has(key)) return true;
+    // Cross-document references: the native engine has no registry of
+    // external schemas, and embedded $id changes the base URI in ways its
+    // resolver gets wrong.
+    if (key === '$ref' && typeof v === 'string' && !v.startsWith('#')) return true;
+    if (key === '$id' && depth > 0) return true;
+    // An empty enum rejects everything; the walker accepts everything.
+    if (key === 'enum' && Array.isArray(v) && v.length === 0) return true;
+    if (key === 'format' && DIVERGENT_FORMATS.has(v)) return true;
+    // Unicode property escapes: RE2 cannot parse them and the walker then
+    // skips the pattern instead of failing.
+    if (key === 'pattern' && typeof v === 'string' && /\\[pP]\{/.test(v)) return true;
+    // Tuple forms: prefixItems and the draft-07 array form of items are
+    // checked against the wrong positions by the walker.
+    if (key === 'prefixItems') return true;
+    if ((key === 'items' || key === 'additionalItems') && (typeof v === 'boolean' || Array.isArray(v))) return true;
+
+    if (SUBSCHEMA_MAPS.includes(key)) {
+      if (v && typeof v === 'object' && !Array.isArray(v)) {
+        for (const k of Object.keys(v)) if (walk(v[k], depth + 1)) return true;
+      }
+    } else if (SUBSCHEMA_NODES.includes(key)) {
+      if (walk(v, depth + 1)) return true;
+    }
+  }
+  return false;
+}
+
+// True when the buffer APIs must answer through validate() for this schema.
+function bufferNeedsSlowPath(schema, schemaMap) {
+  if (walk(schema, 0)) return true;
+  if (schemaMap && schemaMap.size > 0) {
+    for (const s of schemaMap.values()) if (walk(s, 1)) return true;
+  }
+  return false;
+}
+
+function toText(input, name) {
+  if (typeof input === 'string') return input;
+  if (input instanceof Uint8Array) return Buffer.from(input.buffer, input.byteOffset, input.byteLength).toString('utf8');
+  throw new TypeError(`${name}() requires a Buffer, Uint8Array, or string. For parsed objects, use isValidObject().`);
+}
+
+// Replaces the instance's buffer APIs with versions that parse and call
+// validate(). Installed after compilation, so `validator.validate` is final.
+function installSlowBufferApis(validator) {
+  const isValidText = (text) => {
+    let value;
+    try { value = JSON.parse(text); } catch { return false; }
+    return validator.validate(value).valid;
+  };
+  validator.isValid = (input) => isValidText(toText(input, 'isValid'));
+  validator.isValidJSON = (jsonStr) => isValidText(jsonStr);
+  validator.isValidPrepadded = (paddedBuffer, jsonLength) =>
+    isValidText(Buffer.from(paddedBuffer.buffer, paddedBuffer.byteOffset, jsonLength).toString('utf8'));
+  const ndjson = (input, name) => {
+    const lines = toText(input, name).split('\n');
+    const out = [];
+    for (const line of lines) {
+      if (line === '') continue; // the native loop skips zero-length lines only
+      out.push(isValidText(line));
+    }
+    return out;
+  };
+  validator.isValidNDJSON = (input) => ndjson(input, 'isValidNDJSON');
+  validator.isValidParallel = (input) => ndjson(input, 'isValidParallel');
+  validator.countValid = (input) => {
+    let n = 0;
+    for (const ok of ndjson(input, 'countValid')) if (ok) n++;
+    return n;
+  };
+  validator.batchIsValid = (buffers) => {
+    let n = 0;
+    for (const b of buffers) {
+      if (!(b instanceof Uint8Array)) throw new TypeError('batchIsValid() requires Buffer or Uint8Array elements');
+      if (isValidText(toText(b, 'batchIsValid'))) n++;
+    }
+    return n;
+  };
+}
+
+module.exports = { bufferNeedsSlowPath, installSlowBufferApis };

package/lib/draft7.js

@@ -9,15 +9,37 @@ function isDraft7(schema) {
   return !!(schema && schema.$schema && DRAFT7_SCHEMAS.has(schema.$schema))
 }
 
-function normalizeDraft7(schema) {
-  if (!isDraft7(schema)) return schema
+// `force` applies the draft-07 rules to a document that declares no dialect
+// of its own, which is how a retrieved schema inherits the root's draft.
+function normalizeDraft7(schema, force) {
+  if (!force && !isDraft7(schema)) return schema
   _normalize(schema)
   return schema
 }
 
+// Keywords that may sit next to `$ref` in draft-07 without being applied:
+// definitions are addressable by pointer, annotations are inert.
+const REF_SIBLINGS_KEPT = new Set(['$ref', '$defs', 'definitions', '$schema', '$comment', 'title', 'description', 'examples', 'default', 'readOnly', 'writeOnly'])
+
 function _normalize(schema) {
   if (typeof schema !== 'object' || schema === null) return
 
+  // In draft-07 an object with `$ref` is that reference and nothing else:
+  // sibling keywords, `$id` included, are ignored. Dropping them here gives
+  // every engine the same reading without each having to know the draft.
+  if (typeof schema.$ref === 'string') {
+    for (const key of Object.keys(schema)) {
+      if (!REF_SIBLINGS_KEPT.has(key)) delete schema[key]
+    }
+  }
+
+  // A fragment-only `$id` is a plain-name anchor in draft-07; 2020-12 spells
+  // it `$anchor`, which every engine already resolves.
+  if (typeof schema.$id === 'string' && /^#[A-Za-z][A-Za-z0-9_.:-]*$/.test(schema.$id)) {
+    if (schema.$anchor === undefined) schema.$anchor = schema.$id.slice(1)
+    delete schema.$id
+  }
+
   // definitions → $defs
   if (schema.definitions && !schema.$defs) {
     schema.$defs = schema.definitions