ata-validator 1.6.1 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 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
+
+- The Standard Schema surface carried no output type. `~standard.validate()` returned `{ value: unknown }` and the `types` carrier the specification defines for inference was missing, so every consumer that reads the validated type off `~standard` (Fastify, tRPC, TanStack Form, Drizzle) saw `unknown` and needed a cast. `~standard` is now typed against the validator's own data type, and `types.output` carries it. Type-only: the runtime object is unchanged, and the specification defines `types` as never present at runtime.
+- Boolean schemas were rejected by the `Validator` constructor's TypeScript signature. `true` and `false` are schemas anywhere JSON Schema allows one, and both have always worked at runtime; only the types disagreed, which made a schema of unknown shape (`object | boolean`) impossible to pass without a cast. Nested boolean subschemas are still typed as objects, so `{ properties: { a: true } }` needs `defineSchema` or a cast.
+- The `t` builder's option bags rejected vendor keywords. `t.object({}, { instanceof: 'Date' })` is what a custom keyword package expects to be given, and the option types only allowed the keywords the builder itself emits, so callers wrote `as never`. Every option bag now accepts unknown keywords alongside the typed ones.
+- `tests/test_interop_types.ts` covers all three under `tsc --noEmit`.
+
 ## 1.6.1 - 2026-08-09
 
 ### 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:
 
@@ -43,15 +43,30 @@ The `.compiled.mjs` modules are self-contained: zero runtime dependency on ata-v
 
 | Dimension | Schema | ata-AOT | AJV-runtime | Difference |
 |---|---|---|---|---|
-| Bundle (gzipped) | simple | 955 B | 52.7 KB | 56x smaller |
-| Bundle (gzipped) | complex | 1.6 KB | 52.7 KB | 32x smaller |
-| Cold start | simple | 21 ms | 38 ms | 1.8x faster |
-| Throughput (10M ops) | simple | 345 Mops/s | 116 Mops/s | 3.0x faster |
-| Compile time | simple | 6 µs | 1.5 ms | 246x faster |
-
-Reproduce on your machine with `npm run bench:aot-vs-ajv`. Numbers measured on Apple M4 Pro, Node 25.2.1.
-
-The wins are largest on bundle size and compile time because AOT moves work from runtime to build time. Throughput and cold start are also faster because the compiled validator is a tight straight-line function with no schema-walk overhead.
+| Bundle (gzipped) | simple | 1.0 KB | 52.7 KB | 50.5x smaller |
+| Bundle (gzipped) | complex | 4.8 KB | 52.7 KB | 11.0x smaller |
+| Bundle (gzipped) | nested | 2.3 KB | 52.7 KB | 23.1x smaller |
+| Cold start | simple | 21 ms | 40 ms | 1.9x faster |
+| Throughput (1M ops) | simple | 258 Mops/s | 102 Mops/s | 2.5x faster |
+| Compile time | simple | 8 µs | 1.61 ms | 191x faster |
+
+Reproduce on your machine with `npm run bench:aot-vs-ajv`. Numbers from one run on Apple
+M4 Pro, Node 25.2.1, 2026-08-13. Across three runs throughput moved between 258 and 278
+Mops/s and the compile ratio between 150x and 199x, so treat the last two rows as an order
+of magnitude rather than a constant.
+
+The wins are largest on bundle size and compile time because AOT moves work from runtime to
+build time. Throughput and cold start are also faster because the compiled validator is a
+tight straight-line function with no schema-walk overhead.
+
+What the table does not cover is data that fails. It measures compiled modules on input that
+passes, and a rejection costs more than a verdict: ata builds an error carrying a code, the
+offending value, a documentation link and a suggestion. On a five-field object schema a
+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: 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
 
@@ -385,7 +400,10 @@ const { toStandaloneModule } = require('ata-validator/build');
 fs.writeFileSync('./user.validator.mjs', toStandaloneModule(schema, { format: 'esm' }));
 ```
 
-**Fastify startup (10 routes cold): ajv 12.6ms → ata 0.5ms (24x faster boot, no build step required)**
+**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.
+Reproduce with `node benchmark/bench_fastify_boot.mjs`.
 
 ### Standard Schema V1
 
@@ -479,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

@@ -364,13 +364,13 @@ export interface BundleStandaloneOptions extends ValidatorOptions {
   format?: 'esm' | 'cjs';
 }
 
-export interface StandardSchemaV1Props {
+export interface StandardSchemaV1Props<Output = unknown, Input = unknown> {
   version: 1;
   vendor: "ata-validator";
   validate(
     value: unknown
   ):
-    | { value: unknown }
+    | { value: Output }
     | {
         issues: Array<{
           message: string;
@@ -378,6 +378,11 @@ export interface StandardSchemaV1Props {
           path?: ReadonlyArray<{ key: PropertyKey }>;
         }>;
       };
+  /**
+   * Type-only carrier the Standard Schema spec uses for inference: consumers
+   * read the validated type off `types.output`. Never present at runtime.
+   */
+  readonly types?: { readonly input: Input; readonly output: Output } | undefined;
 }
 
 export interface StandaloneModule {
@@ -396,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>;
@@ -425,7 +437,7 @@ export interface Validator<T = unknown> {
   isValidNDJSON(ndjsonBuffer: Buffer): boolean[];
 
   /** Standard Schema V1 interface, compatible with Fastify, tRPC, TanStack, etc. */
-  readonly "~standard": StandardSchemaV1Props;
+  readonly "~standard": StandardSchemaV1Props<T>;
 }
 
 /** Constructor + statics for {@link Validator}. */
@@ -433,7 +445,7 @@ export interface ValidatorConstructor {
   /** Construct from a JSON Schema literal; the validated data type is inferred. */
   new <const S extends JSONSchema>(schema: S, options?: ValidatorOptions): Validator<Infer<S>>;
   /** Construct from a plain object/string schema, or with an explicit data type. */
-  new <T = unknown>(schema: object | string, options?: ValidatorOptions): Validator<T>;
+  new <T = unknown>(schema: object | string | boolean, options?: ValidatorOptions): Validator<T>;
 
   /** Load a pre-compiled standalone module. Zero schema compilation at startup. */
   fromStandalone<T = unknown>(mod: StandaloneModule, schema: object | string, options?: ValidatorOptions): Validator<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;