ata-validator 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 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.12.0 - 2026-09-06
+
+### Performance
+
+- `date-time` stopped asking every character where it sits. The scan tested each of nineteen positions against the separator indices before checking the digit; the separators are now read directly by index and each digit becomes its value in the same read that validates it, so the field numbers cost nothing extra. 40.8 to 19.5 ns on a valid value, medians across separate processes. Same answers as before on every month, day and clock boundary and under 150k random mutations.
+
+- `uuid` reads the four hyphens by index and the 32 hex digits in five runs with fixed bounds, instead of a case-insensitive regular expression. A digit is one unsigned compare and a letter one more after folding case with a single OR. 48.4 to 35.1 ns; 300k mutated and random strings against the old expression with 0 mismatches.
+
+- `time` reads fixed positions the same way instead of running a regular expression: 15.6 to 12.1 ns, and 200k mutations against the old pattern with 0 mismatches.
+
+- `uri` reads the scheme from the front and scans the rest once instead of running two regular expressions: 39.3 to 32.8 ns, interleaved medians. The remaining scan then became two tiers, because the measured answer was not the expected one: a hand-written character loop beat the old `\s` expression in isolation but lost to the engine's scanner inside a compiled validator, since `\s` is what forced the Unicode machinery in. The first tier asks whether anything sits outside printable ASCII, a one-byte class the engine scans at its own speed and no ordinary URI ever trips; only a string that trips it pays for the loop that knows the exact reserved set. On a nested schema carrying six URLs, 215.5 to 189.4 ns per document, medians across separate processes. `uri-reference` shares the same scan. Fuzzed over every code point in the BMP in three positions, 0 mismatches.
+
+- The Standard Schema bridge stopped paying for enrichment it throws away. An issue carries a message and a path and nothing else, but `~standard.validate` read the rich error list, which builds suggestions, ranks and source frames per error. It now takes the raw, schema-ordered list through the same build the rich path uses, and `parsePointerPath` walks the pointer in one pass instead of split, filter, map and a regex per segment. A 16-error rejection went from 17.6 to 4.3 microseconds; messages and order are unchanged, and `tests/test_standard_schema.js` holds issues to exact parity with `validate().errors`. Schemas using `errorMessage` keep their custom messages.
+
+### Fixed
+
+- The compiled engine refused a lowercase zone letter in `time` that the interpreter accepted: `00:00:00z` answered differently depending on which engine ran the schema, and `date-time` took either case in both. One implementation now answers for every engine, and it takes both cases, per RFC 3339.
+
+- The ReDoS integration test measured the first call, which includes compiling the schema and the pattern, against a 50 ms budget. On a loaded CI machine that reads as a failure without anything being wrong: the gate exists to separate linear matching from catastrophic backtracking, which differ by minutes, not by milliseconds. It now warms up first and allows 500 ms.
+
+## 1.11.0 - 2026-08-31
+
+### Fixed
+
+- The verdict methods answer the same question as `validate()` again. With `coerceTypes`, `removeAdditional` or a schema `default` in play, `validate()` ran the preprocess pass and `isValidObject()`, `isValidJSON()` and `validateJSON()` did not, so the same validator answered `true` from one and `false` from another for the same document: `validate({ age: '26' })` accepted where `isValidObject({ age: '26' })` rejected. Every path now runs the same pass. Verdict methods on a validator configured this way rewrite the input in place, as `validate()` already did, and the cost of the correction is 0.5 ns on `isValidObject` and 2.7 ns on `isValidJSON`, measured interleaved; validators without those options are unchanged. `tests/test_verdict_preprocess.js` holds all four methods to the same answers.
+
+- The native engine's error codes no longer reach callers untranslated. A type failure answered by the addon came back as `code: 3` with no `keyword` and a `docUrl` pointing at a page that does not exist, while the same failure from the JavaScript engines came back as `ATA1001`; both now report the documented code, keyword and link. `tests/test_native_error_codes.js` holds the table against the enum in `include/ata.h`, so the two cannot drift apart silently.
+- The error generator declined self-referencing schemas by emitting nothing for the reference, which accepted whatever that reference guarded: `{ properties: { foo: { $ref: "#" } }, additionalProperties: false }` accepted `{ foo: { bar: false } }` on that path. It now declines the schema outright and the validator falls back to an engine that answers it correctly. The entry-point agreement test covers the shape.
+
+- `ipv6` gave two different answers depending on which engine ran it, and neither was right. The compiled path refused an IPv4-mapped address such as `::ffff:192.168.1.1`, the interpreted path accepted `::ffff:1.2.3.4.5`, and both accepted a group of five hex digits like `12345::1`. One implementation now answers for every engine, following RFC 4291, checked against Node's own `net.isIPv6` and the suite's corpus.
+
+- `date-time` refuses dates that do not exist. The check ran a regular expression for the shape and then handed the string to `Date.parse`, which rolls an out-of-range day into the next month, so `2026-02-30T00:00:00Z`, `2026-02-29T00:00:00Z` and `2026-12-31T24:00:00Z` were all accepted. The month, the day count for that month in that year, the clock and the offset are now checked directly, per RFC 3339. Schemas that relied on the old leniency will see those values rejected.
+
+- Data that points back at itself no longer exhausts the stack. A document with a cycle, which JSON text cannot express but an in-memory object graph can, threw `RangeError: Maximum call stack size exceeded` on the compiled path while the interpreted engine settled on an answer, so the two engines disagreed. Both now follow the same rule: a value already being checked against a schema is a fixed point and counts as satisfied, and a cycle no longer hides a real violation elsewhere in the document. Validation runs a fast pass that only counts depth and a guarded pass that runs when that depth is exceeded, so ordinary documents pay one integer operation per recursive call. Measured interleaved on a self-referencing schema: a four-node document 22.2 to 30.6 ns, a 200-node document 2077 to 1178 ns, non-recursive schemas unchanged at 3.8 ns. `tests/test_cyclic_input.js` holds all three engines to the same answers.
+
+### Performance
+
+- `ipv6` and `hostname` read the string once as well: 54.7 to 29.6 ns and 45.5 to 28.2 ns, interleaved medians. `ipv6` no longer allocates two arrays per check; `hostname` keeps the answers of the expression it replaces, fuzzed over 300k strings with 0 mismatches.
+
+- `date-time` reads the string once, with no regular expression, no date object and no allocation: 95.0 to 39.4 ns on a valid value with a `Z`, 103.8 to 45.3 ns with a numeric offset, interleaved medians. Fuzzed against a reference that spells out RFC 3339, with 0 mismatches over 300k strings; `tests/test_formats_single_pass.js` keeps both the predicate and the generated form on it.
+
+- A constructed Validator is roughly three times smaller on the heap until it is used. The public methods and the Standard Schema entry moved from per-instance closures built in the constructor to memoized prototype accessors, and the JSON position cache is only allocated when the JSON text path first needs it. Measured per instance on a 10-key object schema, double-gc deltas over 2000 instances: 1.61 KB to 0.43 KB with a shared schema object, 2.33 KB to 1.12 KB when each instance owns its schema, 3.93 KB to 3.30 KB once compiled and used. Construction alone went from 1504 to 855 ns; construction plus first validate pays about 0.9 microseconds more, once, because the compile step's method assignments now go through a defining setter. The hot validate() path is unchanged, measured interleaved. Detached method references (`const f = v.validate`) still work; `tests/test_lazy_instance.js` pins the shape.
+
 ## 1.10.0 - 2026-08-30
 
 ### Performance

package/index.js

@@ -15,6 +15,7 @@ const { needsNormalization } = require("./lib/schema-scan");
 const { isV1Dialect } = require("./lib/dialect");
 const { classify } = require("./lib/shape-classifier");
 const { buildTier0Plan, tier0Validate } = require("./lib/tier0");
+const { createCache: _createPosCache } = require("./lib/data-position-cache");
 
 // Extract default values from a schema tree. Returns a function that applies
 // defaults to an object in-place (mutates), or null if no defaults exist.
@@ -325,15 +326,22 @@ const ABORT_EARLY_RESULT = Object.freeze({
 // the eager shape. Note for tests: deepStrictEqual against a plain object
 // compares prototypes; read `.errors` and compare that.
 class LazyRejection {
-  constructor(build, data) {
+  constructor(build, data, buildRaw) {
     this.valid = false;
     this._build = build;
     this._data = data;
     this._errors = null;
+    this._buildRaw = buildRaw;
   }
   toJSON() {
     return { valid: false, errors: this.errors };
   }
+  // Raw shape for consumers that carry only message and path, such as the
+  // Standard Schema bridge: schema order, no enrichment. Reading `errors`
+  // afterwards still enriches through its own build.
+  _ataRaw() {
+    return this._buildRaw ? this._buildRaw(this._data) : this.errors;
+  }
 }
 Object.defineProperty(LazyRejection.prototype, 'errors', {
   enumerable: true,
@@ -462,18 +470,30 @@ function sortErrorsBySchemaOrder(rootSchema, errors) {
 
 function parsePointerPath(path) {
   if (!path) return [];
-  return path
-    .split("/")
-    .filter(Boolean)
-    .map((seg) => {
-      const decoded = seg.replace(/~1/g, "/").replace(/~0/g, "~");
-      // Per Standard Schema V1: array indices should be emitted as numbers,
-      // object keys as strings. Treat all-digit segments as numeric indices.
-      if (/^(0|[1-9][0-9]*)$/.test(decoded)) {
-        return { key: Number(decoded) };
+  // One pass, no intermediate arrays. Per Standard Schema V1 an array index
+  // is emitted as a number and an object key as a string; a segment is an
+  // index when it is all digits with no leading zero.
+  const out = [];
+  const n = path.length;
+  let start = 1;
+  for (let i = 1; i <= n; i++) {
+    if (i !== n && path.charCodeAt(i) !== 47) continue;
+    if (i > start) {
+      let seg = path.slice(start, i);
+      if (seg.indexOf('~') >= 0) seg = seg.replace(/~1/g, '/').replace(/~0/g, '~');
+      const c0 = seg.charCodeAt(0);
+      let numeric = c0 >= 48 && c0 <= 57 && (seg.length === 1 || c0 !== 48);
+      if (numeric) {
+        for (let k = 1; k < seg.length; k++) {
+          const c = seg.charCodeAt(k);
+          if (c < 48 || c > 57) { numeric = false; break; }
+        }
       }
-      return { key: decoded };
-    });
+      out.push({ key: numeric ? Number(seg) : seg });
+    }
+    start = i + 1;
+  }
+  return out;
 }
 
 function createPaddedBuffer(jsonStr) {
@@ -788,89 +808,15 @@ class Validator {
     // Per-validate data position cache. Populated by validateJSON before
     // dispatching to inner validate(); consulted by the rich-error wrap
     // to attach dataFrame entries to each enriched error.
-    this._posCache = require('./lib/data-position-cache').createCache();
+    this._posCache = null; // created by _pos() on first use, only the JSON text path needs it
     this._lastRawInput = null;
 
-    // Lazy stubs: trigger compilation on first call, then re-dispatch
-    this.validate = (data) => {
-      this._ensureCompiled();
-      return this.validate(data);
-    };
-    this.isValidObject = (data) => {
-      // Lazy: classify + build tier 0 plan on first call, not in constructor.
-      const _tier = classify(this._schemaObj);
-      if (_tier.tier === 0) {
-        const _plan = buildTier0Plan(this._schemaObj);
-        let _n = 0;
-        this.isValidObject = (d) => {
-          const r = tier0Validate(_plan, d);
-          if (++_n === 2) {
-            try { this._ensureCodegen(); } catch {}
-          }
-          return r;
-        };
-      } else {
-        this._ensureCodegen();
-        // Codegen can bail on shapes it cannot represent; the full compile
-        // binds the native path or the unsupported thrower instead of
-        // leaving this stub to re-dispatch to itself.
-        if (!this._jsFn) this._ensureCompiled();
-      }
-      return this.isValidObject(data);
-    };
-    this.validateJSON = (jsonStr) => {
-      this._ensureCompiled();
-      return this.validateJSON(jsonStr);
-    };
-    this.isValidJSON = (jsonStr) => {
-      this._ensureCompiled();
-      return this.isValidJSON(jsonStr);
-    };
-    this.validateAndParse = (jsonStr) => {
-      if (!native) throw new Error('Native addon required for validateAndParse()');
-      this._ensureCompiled();
-      return this.validateAndParse(jsonStr);
-    };
-    this.isValid = (buf) => {
-      if (!native) throw new Error('Native addon required for isValid() — use validate() or isValidObject() instead');
-      this._ensureCompiled();
-      return this.isValid(buf);
-    };
-    this.countValid = (ndjsonBuf) => {
-      if (!native) throw new Error('Native addon required for countValid()');
-      this._ensureCompiled();
-      return this.countValid(ndjsonBuf);
-    };
-    this.batchIsValid = (buffers) => {
-      if (!native) throw new Error('Native addon required for batchIsValid()');
-      this._ensureCompiled();
-      return this.batchIsValid(buffers);
-    };
+    // Public methods start as memoized accessors on the prototype; nothing is
+    // allocated per instance until one is first read. See _defineLazyMethod
+    // below the class.
 
-    // ~standard uses self.validate() -- works with lazy because it goes through
-    // the instance property which gets swapped after compilation
-    const self = this;
-    Object.defineProperty(this, "~standard", {
-      value: Object.freeze({
-        version: 1,
-        vendor: "ata-validator",
-        validate(value) {
-          const result = self.validate(value);
-          if (result.valid) {
-            return { value };
-          }
-          return {
-            issues: result.errors.map((err) => ({
-              message: err.message,
-              path: parsePointerPath(err.instancePath),
-            })),
-          };
-        },
-      }),
-      writable: false,
-      enumerable: false,
-      configurable: false,
-    });
+    // "~standard" (Standard Schema V1) is a lazy prototype accessor too;
+    // see below the class. Consumers only pay for it if they read it.
 
     // Populate identity cache so repeated `new Validator(sameSchema)` short-circuits.
     if (!opts && typeof schema === "object" && schema !== null) {
@@ -882,6 +828,22 @@ class Validator {
   // meta-schema, which addSchema() may only have registered just now. Run once,
   // before anything reads the schema, and before `_schemaStr` is computed from
   // it. After this addSchema() is refused, so the answer cannot go stale.
+  // Whether validation is preceded by a pass that rewrites the input:
+  // coercion, removal of undeclared keys, or filling in defaults. The verdict
+  // methods have to take the same path when it is, so the quick bindings that
+  // answer from the compiled function alone are not used for these validators.
+  _needsPreprocess() {
+    const o = this._options;
+    if (o.coerceTypes || o.removeAdditional) return true;
+    if (o.useDefaults === false) return false;
+    if (!this._schemaStr) this._schemaStr = JSON.stringify(this._schemaObj);
+    return this._schemaStr.includes('"default"');
+  }
+
+  _pos() {
+    return this._posCache || (this._posCache = _createPosCache());
+  }
+
   _ensureVocabularies() {
     if (this._vocabulariesApplied) return;
     this._vocabulariesApplied = true;
@@ -1180,14 +1142,26 @@ class Validator {
           return result;
         };
       }
-      this.isValidObject = jsFn;
+      // The verdict methods answer validate()'s question without building the
+      // error list, so they run the same preprocess pass. Skipping it made the
+      // two disagree on input that coercion or a default would have fixed.
+      this.isValidObject = preprocess
+        ? (data) => { preprocess(data); return jsFn(data) }
+        : jsFn;
       const hybridFn = jsFn._hybridFactory
         ? jsFn._hybridFactory(VALID_RESULT, errFn)
         : null;
-      const jsonValidateFn = safeCombinedFn
+      const jsonValidateInner = safeCombinedFn
         || hybridFn
         || ((obj) => (jsFn(obj) ? VALID_RESULT : errFn(obj)));
-      this.validateJSON = useSimdjsonForLarge && native
+      // Parsed text takes the same preprocess pass as a parsed object, so
+      // validate(obj) and validateJSON(text) answer the same for the same
+      // document. Without it, coercion, removal and defaults applied on one
+      // path and not the other.
+      const jsonValidateFn = preprocess
+        ? (obj) => { preprocess(obj); return jsonValidateInner(obj) }
+        : jsonValidateInner;
+      this.validateJSON = useSimdjsonForLarge && native && !preprocess
         ? (jsonStr) => {
             if (jsonStr.length >= SIMDJSON_THRESHOLD) {
               this._ensureNative();
@@ -1214,7 +1188,22 @@ class Validator {
             this._ensureNative();
             return this._compiled.validateJSON(jsonStr);
           };
-      this.isValidJSON = useSimdjsonForLarge && native
+      // The addon validates the bytes as they are, which is the wrong answer
+      // when the schema asks for coercion, removal or defaults: those change
+      // what counts as valid. With a preprocess pass configured the text is
+      // parsed and run through the same path validate() takes.
+      const verdictFromText = (jsonStr) => {
+        let parsed;
+        try {
+          parsed = JSON.parse(jsonStr);
+        } catch (e) {
+          if (!(e instanceof SyntaxError)) throw e;
+          return false;
+        }
+        if (preprocess) preprocess(parsed);
+        return jsFn(parsed);
+      };
+      this.isValidJSON = useSimdjsonForLarge && native && !preprocess
         ? (jsonStr) => {
             if (jsonStr.length >= SIMDJSON_THRESHOLD) {
               this._ensureNative();
@@ -1223,21 +1212,9 @@ class Validator {
                 Buffer.from(jsonStr),
               );
             }
-            try {
-              return jsFn(JSON.parse(jsonStr));
-            } catch (e) {
-              if (!(e instanceof SyntaxError)) throw e;
-              return false;
-            }
+            return verdictFromText(jsonStr);
           }
-        : (jsonStr) => {
-            try {
-              return jsFn(JSON.parse(jsonStr));
-            } catch (e) {
-              if (!(e instanceof SyntaxError)) throw e;
-              return false;
-            }
-          };
+        : verdictFromText;
       // validateAndParse: parse the JSON, then validate. Pure JS (JSON.parse +
       // validate) so it works with or without the native addon and in browsers.
       {
@@ -1416,11 +1393,19 @@ class Validator {
         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;
+          const positions = (enrich && self._lastRawInput != null) ? self._pos().get(self._lastRawInput) : null;
           if (positions) self._posCache.reset();
           let cached = null;
           return {
             valid: false,
+            // Raw shape for consumers that carry only message and path, such
+            // as the Standard Schema bridge: schema order, no enrichment.
+            // Reading `errors` afterwards still enriches from the same build.
+            _ataRaw() {
+              let raw = result.errors || [];
+              if (raw.length > 1) raw = sortErrorsBySchemaOrder(root, raw);
+              return raw;
+            },
             get errors() {
               if (cached === null) {
                 let raw = result.errors || [];
@@ -1481,7 +1466,7 @@ class Validator {
             let parsedData;
             try { parsedData = JSON.parse(jsonStr); } catch { parsedData = undefined; }
             if (!first || !first.docUrl) {
-              const positions = (this._lastRawInput != null) ? this._posCache.get(this._lastRawInput) : null;
+              const positions = (this._lastRawInput != null) ? this._pos().get(this._lastRawInput) : null;
               const enriched = result.errors.map((e) => enrich(e, {
                 data: parsedData,
                 positions,
@@ -1501,7 +1486,7 @@ class Validator {
               return { valid: false, errors: enriched };
             }
             // Already-enriched path: still attach dataFrame if missing.
-            const positions = (this._lastRawInput != null) ? this._posCache.get(this._lastRawInput) : null;
+            const positions = (this._lastRawInput != null) ? this._pos().get(this._lastRawInput) : null;
             if (positions) {
               for (const e of result.errors) {
                 if (e && !e.dataFrame) {
@@ -1592,17 +1577,24 @@ class Validator {
       const _full = this.validate;
       const _fast = this._fastVerdict;
       const EMPTY_ERRORS = Object.freeze([]);
+      const _verdictFallback = [{ keyword: 'validation', instancePath: '', schemaPath: '#', params: {}, message: 'schema validation failed' }];
       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' }];
+          : _verdictFallback;
+      };
+      const _buildRawErrors = (data) => {
+        const r = _full(data);
+        if (!r || r.valid !== false) return _verdictFallback;
+        const raw = typeof r._ataRaw === 'function' ? r._ataRaw() : r.errors;
+        return raw && raw.length ? raw : _verdictFallback;
       };
       this.validate = (data) => {
         if (_fast(data)) return { valid: true, data, errors: EMPTY_ERRORS };
-        return new LazyRejection(_buildErrors, data);
+        return new LazyRejection(_buildErrors, data, _buildRawErrors);
       };
     }
 
@@ -1673,6 +1665,13 @@ class Validator {
 
   _ensureCodegen() {
     if (this._jsFn) return;
+    // A validator that rewrites its input cannot use the binding below: that
+    // one answers from the compiled function alone and would skip the rewrite,
+    // so isValidObject() and validate() would disagree.
+    if (this._needsPreprocess()) {
+      this._ensureCompiled();
+      return;
+    }
     this._ensureVocabularies();
     if (typeof process !== 'undefined' && process.env && process.env.ATA_FORCE_NAPI) return;
     if (!this._schemaStr) this._schemaStr = JSON.stringify(this._schemaObj);
@@ -2032,6 +2031,132 @@ function defineSchema (schema) {
   return schema;
 }
 
+// Public methods start as memoized accessors on the prototype. A fresh
+// Validator allocates none of them; the first read of a method builds the
+// bound closure, stores it on the instance as an ordinary writable property
+// and returns it. The setter keeps the compile step's plain assignments
+// (`this.validate = fn`) working before the getter has ever run. Detached
+// use (`const f = v.validate`) keeps working because the closure binds the
+// instance.
+// Standard Schema V1. Built on first read, then pinned to the instance with
+// the same descriptor the constructor used to install eagerly.
+Object.defineProperty(Validator.prototype, "~standard", {
+  configurable: true,
+  get() {
+    const self = this;
+    const std = Object.freeze({
+      version: 1,
+      vendor: "ata-validator",
+      validate(value) {
+        const result = self.validate(value);
+        if (result.valid) {
+          return { value };
+        }
+        // An issue carries a message and a path and nothing else, so the
+        // suggestion and source-frame work the rich error path does would be
+        // thrown away here. Take the raw, schema-ordered list when the result
+        // offers one; fall back to the public list otherwise.
+        const raw = typeof result._ataRaw === 'function' ? result._ataRaw() : result.errors;
+        const issues = new Array(raw.length);
+        for (let i = 0; i < raw.length; i++) {
+          const err = raw[i];
+          const path = err.instancePath != null ? err.instancePath : (err.path || '');
+          let message = err.message;
+          if (!message) {
+            // The native engine reports numeric codes without a message; the
+            // enrich pass knows how to word those. Rare, so required lazily.
+            message = require('./lib/enrich-error').enrich(err, {}).message;
+          }
+          issues[i] = { message, path: parsePointerPath(path) };
+        }
+        return { issues };
+      },
+    });
+    Object.defineProperty(this, "~standard", {
+      value: std,
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    });
+    return std;
+  },
+});
+
+function _defineLazyMethod(name, maker) {
+  Object.defineProperty(Validator.prototype, name, {
+    configurable: true,
+    get() {
+      const fn = maker(this);
+      Object.defineProperty(this, name, { value: fn, writable: true, configurable: true, enumerable: true });
+      return fn;
+    },
+    set(fn) {
+      Object.defineProperty(this, name, { value: fn, writable: true, configurable: true, enumerable: true });
+    },
+  });
+}
+
+_defineLazyMethod('validate', (self) => (data) => {
+  self._ensureCompiled();
+  return self.validate(data);
+});
+_defineLazyMethod('isValidObject', (self) => (data) => {
+  // A validator that rewrites its input goes through the full compile, which
+  // binds a verdict method that runs the rewrite first.
+  if (self._needsPreprocess()) {
+    self._ensureCompiled();
+    return self.isValidObject(data);
+  }
+  // Lazy: classify + build tier 0 plan on first call, not in constructor.
+  const _tier = classify(self._schemaObj);
+  if (_tier.tier === 0) {
+    const _plan = buildTier0Plan(self._schemaObj);
+    let _n = 0;
+    self.isValidObject = (d) => {
+      const r = tier0Validate(_plan, d);
+      if (++_n === 2) {
+        try { self._ensureCodegen(); } catch {}
+      }
+      return r;
+    };
+  } else {
+    self._ensureCodegen();
+    // Codegen can bail on shapes it cannot represent; the full compile
+    // binds the native path or the unsupported thrower instead of
+    // leaving this stub to re-dispatch to itself.
+    if (!self._jsFn) self._ensureCompiled();
+  }
+  return self.isValidObject(data);
+});
+_defineLazyMethod('validateJSON', (self) => (jsonStr) => {
+  self._ensureCompiled();
+  return self.validateJSON(jsonStr);
+});
+_defineLazyMethod('isValidJSON', (self) => (jsonStr) => {
+  self._ensureCompiled();
+  return self.isValidJSON(jsonStr);
+});
+_defineLazyMethod('validateAndParse', (self) => (jsonStr) => {
+  if (!native) throw new Error('Native addon required for validateAndParse()');
+  self._ensureCompiled();
+  return self.validateAndParse(jsonStr);
+});
+_defineLazyMethod('isValid', (self) => (buf) => {
+  if (!native) throw new Error('Native addon required for isValid() — use validate() or isValidObject() instead');
+  self._ensureCompiled();
+  return self.isValid(buf);
+});
+_defineLazyMethod('countValid', (self) => (ndjsonBuf) => {
+  if (!native) throw new Error('Native addon required for countValid()');
+  self._ensureCompiled();
+  return self.countValid(ndjsonBuf);
+});
+_defineLazyMethod('batchIsValid', (self) => (buffers) => {
+  if (!native) throw new Error('Native addon required for batchIsValid()');
+  self._ensureCompiled();
+  return self.batchIsValid(buffers);
+});
+
 module.exports = {
   Validator,
   compile,

package/lib/enrich-error.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { CODES, codeFor } = require('./error-codes');
+const { CODES, codeFor, fromNative } = require('./error-codes');
 const { suggestFor } = require('./suggestions');
 
 const DOC_BASE = 'https://ata-validator.com/e/';
@@ -130,12 +130,19 @@ function rankFor (keyword) {
 function enrich (rawErr, opts) {
   const data = opts && opts.data;
   const positions = opts && opts.positions;
-  const keyword = rawErr.keyword;
   const format = rawErr.params && rawErr.params.format;
+  // The native engine reports its own enum as a number. Translate it to the
+  // keyword and public code the JavaScript engines use, so an error means the
+  // same thing whichever engine produced it.
+  const fromAddon = typeof rawErr.code === 'number' ? fromNative(rawErr.code, format) : null;
+  const keyword = rawErr.keyword || (fromAddon && fromAddon.keyword);
   // Prefer a code the codegen already attached (e.g. branch-collapse emits
   // ATA4001/4002/4003 distinguishing zero/multi/anyOf failure modes). The
   // keyword-derived lookup only finds the first match for `keyword: 'oneOf'`.
-  const code = rawErr.code || codeFor(keyword, format) || 'ATA9001';
+  const code = (fromAddon && fromAddon.code) ||
+    (typeof rawErr.code === 'string' && rawErr.code) ||
+    codeFor(keyword, format) ||
+    'ATA9001';
   const meta = CODES[code];
   const path = rawErr.instancePath != null ? rawErr.instancePath : (rawErr.path || '');
 

package/lib/error-codes.js

@@ -100,4 +100,57 @@ function codeFor (keyword, format) {
   return hit === undefined ? null : hit;
 }
 
-module.exports = { CODES, get, all, codeFor };
+
+// The native engine reports its own `error_code` enum from include/ata.h as an
+// ordinal. Nothing outside the addon should ever see one: an error that came
+// from there carries the same public code and keyword as the same failure from
+// the JavaScript engines. Ordinals are positional, so this table follows the
+// enum's declaration order and `tests/test_native_error_codes.js` fails if the
+// two drift apart.
+const NATIVE_KEYWORDS = [
+  null,                     // 0 ok
+  '__parse__',              // 1 invalid_json
+  '__compile__',            // 2 invalid_schema
+  'type',                   // 3 type_mismatch
+  'required',               // 4 required_property_missing
+  'additionalProperties',   // 5 additional_property_not_allowed
+  'enum',                   // 6 enum_mismatch
+  'const',                  // 7 const_mismatch
+  'minimum',                // 8 minimum_violation
+  'maximum',                // 9 maximum_violation
+  'exclusiveMinimum',       // 10 exclusive_minimum_violation
+  'exclusiveMaximum',       // 11 exclusive_maximum_violation
+  'minLength',              // 12 min_length_violation
+  'maxLength',              // 13 max_length_violation
+  'pattern',                // 14 pattern_mismatch
+  'format',                 // 15 format_mismatch
+  'minItems',               // 16 min_items_violation
+  'maxItems',               // 17 max_items_violation
+  'uniqueItems',            // 18 unique_items_violation
+  'minProperties',          // 19 min_properties_violation
+  'maxProperties',          // 20 max_properties_violation
+  'multipleOf',             // 21 multiple_of_violation
+  'allOf',                  // 22 all_of_failed
+  'anyOf',                  // 23 any_of_failed
+  'oneOf',                  // 24 one_of_failed
+  'not',                    // 25 not_failed
+  '$ref',                   // 26 ref_not_found
+  'if',                     // 27 if_then_else_failed
+]
+
+// Keyword and public code for a native ordinal, or null when the ordinal is
+// outside the enum, which would mean the addon is newer than this table.
+function fromNative (ordinal, format) {
+  if (typeof ordinal !== 'number' || !Number.isInteger(ordinal)) return null
+  const keyword = NATIVE_KEYWORDS[ordinal]
+  if (!keyword) return null
+  // codeFor('format') answers with the first format code, which names a
+  // specific format. Without knowing which format failed, the generic one is
+  // the honest answer.
+  const code = keyword === 'format'
+    ? (format ? codeFor('format', format) || 'ATA3099' : 'ATA3099')
+    : codeFor(keyword) || 'ATA9001'
+  return { keyword, code }
+}
+
+module.exports = { CODES, get, all, codeFor, fromNative, NATIVE_KEYWORDS };