ata-validator 1.59.0 → 1.61.0

package/lib/validator-core.js

@@ -19,6 +19,14 @@ const { normalizeKeywords, schemaUsesKeywords } = require('./keywords');
 // bundle built from lite.js never contains it. Until something registers, the
 // core behaves exactly as it does where `new Function` is blocked: every
 // schema runs on the interpreted engine, which passes the same test suite.
+// Whether this process runs code compiled ahead of time, where generated
+// code falls to an interpreter: Bun's flag for its compiler, or the
+// environment saying so (an executable built before the flag existed).
+function aotHost() {
+  if (env('ATA_ENGINE') === 'interpreter') return true;
+  const b = typeof Bun !== 'undefined' ? Bun : undefined;
+  return !!(b && b.isAOT === true);
+}
 let _codegen = null;
 let compileToJS, compileToJSCodegen, compileToJSCodegenWithErrors, compileToJSCombined;
 function _registerCodegen(engine) {
@@ -37,6 +45,10 @@ let _aotLoader = null;
 // index.browser.mjs, null in every other entry, which then carry none of it.
 let _tiering = null;
 function _registerTiering(t) { _tiering = t; }
+// Called with each validator the constructor finishes. The Node entry uses it
+// to warm the engine once the event loop is free (see index.js).
+let _onBuilt = null;
+function _registerBuiltHook(f) { _onBuilt = f; }
 function _registerAot(load) {
   _aotLoader = load;
 }
@@ -358,64 +370,6 @@ function _jsonSyntaxRejection(e) {
 
 
 
-// Paths repeat across rejections of the same shape, so the parsed segment
-// list is cached per path string. Entries are frozen: the same array is
-// handed to every issue that names the path.
-//
-// The cache is bucketed by length and searched with ===, not keyed in a Map.
-// A path with an array index in it is concatenated afresh by every rejection,
-// and a Map has to hash each such string from scratch before it can look
-// anything up; that hashing was 30% of a Standard Schema rejection with
-// sixteen issues. Comparing against the few paths of the same length costs
-// less. Both levels are bounded so a stream of array indexes cannot grow it
-// without limit: a full bucket stops caching, too many lengths clear it.
-const _pathBuckets = new Map();
-const PATH_BUCKET_MAX = 32;
-const PATH_LENGTHS_MAX = 256;
-function parsePointerPath(path) {
-  if (!path) return EMPTY_PATH;
-  const n = path.length;
-  let bucket = _pathBuckets.get(n);
-  if (bucket !== undefined) {
-    for (let i = 0; i < bucket.length; i += 2) if (bucket[i] === path) return bucket[i + 1];
-  } else {
-    if (_pathBuckets.size >= PATH_LENGTHS_MAX) _pathBuckets.clear();
-    bucket = [];
-    _pathBuckets.set(n, bucket);
-  }
-  const segs = Object.freeze(parsePointerPathUncached(path));
-  if (bucket.length < PATH_BUCKET_MAX * 2) bucket.push(path, segs);
-  return segs;
-}
-const EMPTY_PATH = Object.freeze([]);
-
-function parsePointerPathUncached(path) {
-  // 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; }
-        }
-      }
-      out.push({ key: numeric ? Number(seg) : seg });
-    }
-    start = i + 1;
-  }
-  return out;
-}
-
 function createPaddedBuffer(jsonStr) {
   if (typeof Buffer === 'undefined') throw new Error('createPaddedBuffer requires Node.js Buffer');
   const jsonBuf = Buffer.from(jsonStr);
@@ -830,7 +784,13 @@ class Validator {
     if (options.engine !== undefined && options.engine !== 'auto' && options.engine !== 'interpreter') {
       throw new TypeError("engine must be 'auto' or 'interpreter', got " + JSON.stringify(options.engine));
     }
-    this._interpretOnly = options.engine === 'interpreter';
+    // Under an ahead-of-time compiler the generated code is interpreted and
+    // the interpreted engine, plain JavaScript, is compiled: measured on
+    // Bun's compiler, 80 against 530 ns a document. So the default flips
+    // there: Bun.isAOT once Bun ships it, ATA_ENGINE=interpreter until then
+    // and for any other host. `engine: 'auto'` asked for by name keeps the
+    // generated code.
+    this._interpretOnly = options.engine === 'interpreter' || (options.engine === undefined && aotHost());
     this._initialized = false;
     this._nativeReady = false;
     this._compiled = null;
@@ -919,8 +879,10 @@ class Validator {
     this._verdictTail = null;
     this._validateTail = null;
     this._entryExt = null;
-    // The browser build warms the engine once, when the page is idle (lib/tiering.js).
+    // The browser build warms the engine once, when the page is idle (lib/tiering.js);
+    // the Node entry does the same once the event loop is free (index.js).
     if (_tiering !== null) _tiering.built(this);
+    if (_onBuilt !== null) _onBuilt(this);
 
     // Public methods start as memoized accessors on the prototype; nothing is
     // allocated per instance until one is first read. See _defineLazyMethod
@@ -1008,7 +970,10 @@ class Validator {
 
     // 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);
+    // The generated code takes the form of the target engine (js-compiler's
+    // setTargetEngine), so a function written for one engine is never handed
+    // to a compile asked for the other in the same process.
+    const mapKey = compileCacheKey(this._schemaStr, this._schemaMap) + '\u0000' + (_codegen && _codegen.jsCompiler && typeof _codegen.jsCompiler.targetEngine === 'function' ? _codegen.jsCompiler.targetEngine() : 'v8');
     var _forceNapi = this._interpretOnly || env('ATA_FORCE_NAPI');
     // Custom formats are JS functions: bypass the compile cache since they can
     // differ between validators that share the same schema string. An
@@ -1838,23 +1803,9 @@ class Validator {
       }
     };
 
-    // Standard Schema V1
+    // Standard Schema V1, the same object a Validator hands out.
     Object.defineProperty(v, "~standard", {
-      value: Object.freeze({
-        version: 1,
-        vendor: "ata-validator",
-        jsonSchema: standardJsonSchema(() => schemaObj),
-        validate(value) {
-          const result = v.validate(value);
-          if (result.valid) return { value };
-          return {
-            issues: result.errors.map((e) => ({
-              message: e.message,
-              path: parsePointerPath(e.instancePath),
-            })),
-          };
-        },
-      }),
+      value: require('./standard-schema').standardSchemaFor(v, () => schemaObj, (self, value) => self.validate(value)),
       writable: false,
       enumerable: false,
       configurable: false,
@@ -1985,6 +1936,14 @@ function compile(schema, opts) {
 // JSONSchema type (see index.d.ts) to an inline schema object so TypeScript
 // gives autocomplete and value checking while authoring. Returns the schema
 // untouched so it can be passed straight to Validator, toStandaloneModule, etc.
+// `schemaOf<T>()`: the JSON Schema of a TypeScript type, written in by
+// @ata-project/unplugin at build time from the type and its JSDoc tags. It
+// has no run-time form: a call that reaches here was not replaced, and the
+// loud error is better than an empty schema that accepts everything.
+function schemaOf () {
+  throw new Error('schemaOf<T>() is replaced at build time by @ata-project/unplugin (with ts-json-schema-generator installed); it has no run-time form. Write the JSON Schema, or build with the plugin.');
+}
+
 function defineSchema (schema) {
   return schema;
 }
@@ -1994,74 +1953,19 @@ function defineSchema (schema) {
 // 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
-// Standard JSON Schema, the `jsonSchema` member of `~standard`: what a consumer
-// such as the MCP SDK reads to publish a schema, from `input({ target })`.
-// ata validates the JSON Schema it was given and does not transform values, so
-// input and output are the same document, handed back as a copy when the
-// target is the schema's dialect: draft-07 when it declares draft-07, 2020-12
-// when it declares 2020-12 or nothing, as ata reads it. Any other target
-// throws, as the specification asks, rather than returning a document that
-// would mean something else there.
-function standardJsonSchema(getSchema) {
-  const convert = (options) => {
-    const target = options && options.target;
-    const schema = getSchema();
-    if (schema === true) return {};
-    if (schema === false) return { not: {} };
-    const declared = typeof schema.$schema === 'string' ? schema.$schema : '';
-    const dialect = declared === '' || declared.includes('draft/2020-12/schema') ? 'draft-2020-12'
-      : declared.includes('draft-07/schema') ? 'draft-07' : declared;
-    if (target !== dialect) {
-      throw new TypeError(`ata-validator cannot provide a ${dialect} schema as ${String(target)}; it does not convert between dialects`);
-    }
-    return JSON.parse(JSON.stringify(schema));
-  };
-  return Object.freeze({ input: convert, output: convert });
-}
-
 // 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.
+// Lazy on the prototype, pinned to the instance on first read; the object
+// comes from lib/standard-schema.js, shared with the wrapper around a module
+// written ahead of time, and loaded only when something reads `~standard`.
 Object.defineProperty(Validator.prototype, "~standard", {
   configurable: true,
+  enumerable: false,
   get() {
-    const self = this;
-    const std = Object.freeze({
-      version: 1,
-      vendor: "ata-validator",
-      jsonSchema: standardJsonSchema(() => self._rawSchema),
-      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('./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,
-    });
+    const std = require('./standard-schema').standardSchemaFor(this, (self) => self._rawSchema, (self, value) => self.validate(value));
+    Object.defineProperty(this, "~standard", { value: std, writable: false, enumerable: false, configurable: false });
     return std;
   },
 });
@@ -2529,12 +2433,14 @@ module.exports = {
   SIMDJSON_PADDING,
   parseJSON,
   defineSchema,
+  schemaOf,
 };
 // How an entry registers the code generator. Not enumerable, so the exported
 // surface of `require('ata-validator')` is what it was.
 Object.defineProperty(module.exports, '_registerCodegen', { value: _registerCodegen, enumerable: false });
 Object.defineProperty(module.exports, '_setCodegenLoader', { value: (load) => { _loadCodegen = load; }, enumerable: false });
 Object.defineProperty(module.exports, '_registerTiering', { value: _registerTiering, enumerable: false });
+Object.defineProperty(module.exports, '_registerBuiltHook', { value: _registerBuiltHook, enumerable: false });
 Object.defineProperty(module.exports, '_codegenRegistered', { value: () => _codegen !== null, enumerable: false });
 Object.defineProperty(module.exports, '_tiering', { get: () => _tiering, enumerable: false });
 Object.defineProperty(module.exports, '_registerAot', { value: _registerAot, enumerable: false });

package/lib/verify.js

@@ -0,0 +1,321 @@
+'use strict'
+// `ata verify`: the proof that a compiled module answers as the runtime
+// Validator does, run against a project's own schemas. For every schema the
+// module written by `ata build` is loaded, documents are made from the schema
+// (valid ones, and ones with one rule broken) and read from the project's
+// samples, and both the module and a Validator built from the schema at
+// verification time answer each one; the verdicts and the error lists have to
+// agree. The module's schema hash is checked against the schema as it is now,
+// so a module built from an older schema is reported stale.
+//
+// A validator that wrongly rejects gets a bug report; one that wrongly accepts
+// does not. This command exists so a build-time module gets checked in CI the
+// way the engine is checked here, on every change.
+
+const fs = require('fs')
+const path = require('path')
+const { pathToFileURL } = require('url')
+
+// A small deterministic generator (xorshift32), so a run can be repeated.
+function rng (seed) {
+  let x = (seed >>> 0) || 0x9e3779b9
+  const next = () => { x ^= x << 13; x ^= x >>> 17; x ^= x << 5; return (x >>> 0) / 4294967296 }
+  return { next, int: (n) => Math.floor(next() * n), pick: (a) => a[Math.floor(next() * a.length)], chance: (p) => next() < p }
+}
+
+const WORDS = ['ada', 'Zoë', 'order', 'x', 'north-west', 'a b', 'ÄÖÜ', 'sku-1001', 'TENOFF', 'hello world', '', '0', 'null', '😀', 'line\nbreak', '  ']
+// Strings tried against a `pattern` the generator cannot read: the common
+// shapes of identifiers, codes, addresses, dates and numbers.
+const PATTERN_CANDIDATES = [
+  'a', 'ab', 'abc', 'abc-123', 'ABC', 'A1', 'x_y', 'hello', 'Hello World', 'sku-1001', 'SKU-1001', 'TENOFF',
+  'zoe@example.com', 'a@b.co', 'user.name+tag@example.org', '2026-10-25', '2026-10-25T10:00:00Z', '10:00:00',
+  '0', '1', '42', '-7', '3.14', '1e3', '0001', '+905551112233', '555-1234', '#fff', '#a1b2c3',
+  'https://example.com/path', 'http://x.io', 'example.com', '/a/b/c', 'v1.2.3', '1.2.3', 'en-US', 'TR',
+  '123e4567-e89b-12d3-a456-426614174000', '192.168.0.1', '::1', 'true', 'null', 'aaaaaaaaaaaaaaaa', 'ÄÖÜ', 'çş'
+]
+const FORMAT_EXAMPLES = {
+  email: ['zoe@example.com', 'a@b.co', 'not an email', 'x@', '@y.com'],
+  'date-time': ['2026-10-25T10:00:00Z', '2026-10-25T10:00:00+03:00', '2026-10-25 10:00', 'yesterday'],
+  date: ['2026-10-25', '2026-13-01', '2026-2-5'],
+  time: ['10:00:00Z', '25:00:00Z', '10:00'],
+  uuid: ['123e4567-e89b-12d3-a456-426614174000', '123e4567-e89b-12d3-a456', 'not-a-uuid'],
+  uri: ['https://example.com/a?b=1', 'example.com', '/relative', 'mailto:a@b.co'],
+  'uri-reference': ['https://example.com', '/path', '#frag', ' spaced'],
+  ipv4: ['192.168.0.1', '256.1.1.1', '1.2.3'],
+  ipv6: ['::1', '2001:db8::1', '2001:db8:::1', '1.2.3.4'],
+  hostname: ['example.com', 'a-b.c', '-bad.com', 'x'.repeat(70)],
+  regex: ['^a+$', '([', '\\d+'],
+  'json-pointer': ['/a/b', 'a/b', '/a~1b', '/a~2'],
+}
+
+// A value meant to satisfy `schema`, built from its keywords; where the
+// schema says little, something plausible of the kind.
+function makeValid (schema, r, defs, depth) {
+  if (schema === true || schema === undefined) return r.pick([1, 'x', true, null, {}, []])
+  if (schema === false) return undefined
+  if (typeof schema !== 'object' || schema === null) return null
+  if (schema.$ref !== undefined && typeof schema.$ref === 'string') {
+    const t = resolveLocal(schema.$ref, defs)
+    if (t !== undefined && depth < 6) return makeValid(t, r, defs, depth + 1)
+  }
+  if (schema.const !== undefined) return clone(schema.const)
+  if (Array.isArray(schema.enum) && schema.enum.length) return clone(r.pick(schema.enum))
+  if (Array.isArray(schema.oneOf) && schema.oneOf.length) return makeValid(r.pick(schema.oneOf), r, defs, depth + 1)
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length) return makeValid(r.pick(schema.anyOf), r, defs, depth + 1)
+  if (Array.isArray(schema.allOf) && schema.allOf.length) return makeValid(mergeAllOf(schema), r, defs, depth + 1)
+  let type = schema.type
+  if (Array.isArray(type)) type = r.pick(type)
+  if (type === undefined) {
+    if (schema.properties || schema.required || schema.additionalProperties !== undefined) type = 'object'
+    else if (schema.items || schema.prefixItems || schema.minItems !== undefined) type = 'array'
+    else if (schema.minLength !== undefined || schema.maxLength !== undefined || schema.pattern !== undefined || schema.format !== undefined) type = 'string'
+    else if (schema.minimum !== undefined || schema.maximum !== undefined || schema.multipleOf !== undefined) type = 'number'
+    else type = r.pick(['string', 'number', 'object', 'array', 'boolean', 'null'])
+  }
+  switch (type) {
+    case 'null': return null
+    case 'boolean': return r.chance(0.5)
+    case 'integer':
+    case 'number': {
+      let lo = schema.minimum !== undefined ? schema.minimum : schema.exclusiveMinimum !== undefined && typeof schema.exclusiveMinimum === 'number' ? schema.exclusiveMinimum + 1 : -1000
+      let hi = schema.maximum !== undefined ? schema.maximum : schema.exclusiveMaximum !== undefined && typeof schema.exclusiveMaximum === 'number' ? schema.exclusiveMaximum - 1 : 1000
+      if (hi < lo) hi = lo
+      let v = lo + r.next() * (hi - lo)
+      if (type === 'integer' || r.chance(0.6)) v = Math.round(v)
+      if (typeof schema.multipleOf === 'number' && schema.multipleOf > 0) v = Math.round(v / schema.multipleOf) * schema.multipleOf
+      if (v < lo) v = lo
+      if (v > hi) v = hi
+      return v
+    }
+    case 'string': {
+      if (schema.format && FORMAT_EXAMPLES[schema.format]) return r.pick(FORMAT_EXAMPLES[schema.format])
+      const min = schema.minLength || 0
+      const max = schema.maxLength !== undefined ? schema.maxLength : Math.max(min, 12)
+      if (schema.pattern) {
+        const simple = /^\^?\[([a-zA-Z0-9-]+)\]([+*])?\$?$/.exec(schema.pattern)
+        if (simple) {
+          const set = simple[1].includes('a-z') ? 'abcdefgh' : simple[1].includes('0-9') ? '0123456789' : simple[1].includes('A-Z') ? 'ABCDEFGH' : simple[1].replace(/-/g, '')
+          let s = ''
+          const n = Math.max(min, Math.min(max, 1 + r.int(8)))
+          for (let i = 0; i < n; i++) s += set[r.int(set.length)]
+          return s
+        }
+        // Any other pattern: a candidate that matches, when one does, so the
+        // generated documents reach past the pattern; else a word, which the
+        // schema then refuses, and that is a document too.
+        let re = null
+        try { re = new RegExp(schema.pattern, 'u') } catch {}
+        if (re) {
+          const matching = PATTERN_CANDIDATES.filter((c) => re.test(c) && [...c].length >= min && [...c].length <= max)
+          if (matching.length) return r.pick(matching)
+        }
+      }
+      let s = r.pick(WORDS)
+      while ([...s].length < min) s += 'a'
+      if ([...s].length > max) s = [...s].slice(0, max).join('')
+      return s
+    }
+    case 'array': {
+      const min = schema.minItems || 0
+      const max = schema.maxItems !== undefined ? schema.maxItems : Math.max(min, 4)
+      const n = depth > 4 ? min : min + r.int(Math.max(1, max - min + 1))
+      const out = []
+      for (let i = 0; i < n; i++) {
+        const sub = Array.isArray(schema.prefixItems) && i < schema.prefixItems.length ? schema.prefixItems[i] : Array.isArray(schema.items) ? (schema.items[i] !== undefined ? schema.items[i] : schema.additionalItems) : schema.items
+        if (sub === false) break
+        out.push(makeValid(sub === undefined ? true : sub, r, defs, depth + 1))
+      }
+      if (schema.uniqueItems) return out.filter((v, i, a) => a.findIndex((w) => JSON.stringify(w) === JSON.stringify(v)) === i)
+      return out
+    }
+    case 'object':
+    default: {
+      const out = {}
+      const props = schema.properties && typeof schema.properties === 'object' ? schema.properties : {}
+      const required = new Set(Array.isArray(schema.required) ? schema.required : [])
+      for (const k of Object.keys(props)) {
+        if (k === '__proto__') continue
+        if (required.has(k) || r.chance(0.7)) out[k] = makeValid(props[k], r, defs, depth + 1)
+      }
+      for (const k of required) if (!(k in out) && k !== '__proto__') out[k] = makeValid(props[k] === undefined ? true : props[k], r, defs, depth + 1)
+      if (schema.additionalProperties !== false && !schema.patternProperties && r.chance(0.2) && depth < 4) out[`extra${r.int(3)}`] = makeValid(typeof schema.additionalProperties === 'object' ? schema.additionalProperties : true, r, defs, depth + 1)
+      if (schema.patternProperties && r.chance(0.5)) {
+        for (const [p, sub] of Object.entries(schema.patternProperties)) {
+          const m = /^\^?([a-zA-Z_]+)/.exec(p)
+          if (m) out[m[1] + r.int(9)] = makeValid(sub, r, defs, depth + 1)
+        }
+      }
+      return out
+    }
+  }
+}
+
+function mergeAllOf (schema) {
+  const merged = {}
+  for (const b of schema.allOf) if (typeof b === 'object' && b !== null) Object.assign(merged, b, { properties: { ...(merged.properties || {}), ...(b.properties || {}) }, required: [...(merged.required || []), ...(b.required || [])] })
+  for (const k of Object.keys(schema)) if (k !== 'allOf' && merged[k] === undefined) merged[k] = schema[k]
+  return merged
+}
+
+function resolveLocal (ref, defs) {
+  const m = /^#\/(\$defs|definitions)\/([^/]+)$/.exec(ref)
+  if (!m || !defs[m[1]]) return undefined
+  const key = decodeURIComponent(m[2].replace(/~1/g, '/').replace(/~0/g, '~'))
+  return Object.prototype.hasOwnProperty.call(defs[m[1]], key) ? defs[m[1]][key] : undefined
+}
+
+function clone (v) { return v === undefined ? v : JSON.parse(JSON.stringify(v)) }
+
+// One rule broken somewhere in `doc`: a kind swapped, a key dropped or added,
+// a number pushed out of range, a string lengthened or emptied, an array
+// emptied or an element duplicated. The point is a document the schema is
+// likely to refuse, so both engines get to disagree on refusals too.
+function mutate (doc, r) {
+  const paths = []
+  const walk = (v, p) => {
+    paths.push(p)
+    if (Array.isArray(v)) v.forEach((x, i) => walk(x, [...p, i]))
+    else if (v && typeof v === 'object') for (const k of Object.keys(v)) walk(v[k], [...p, k])
+  }
+  walk(doc, [])
+  const p = r.pick(paths)
+  const get = (o, q) => q.reduce((a, k) => (a == null ? a : a[k]), o)
+  const set = (o, q, val) => { if (q.length === 0) return val; const parent = get(o, q.slice(0, -1)); if (parent != null) parent[q[q.length - 1]] = val; return o }
+  const del = (o, q) => { const parent = get(o, q.slice(0, -1)); if (Array.isArray(parent)) parent.splice(q[q.length - 1], 1); else if (parent) delete parent[q[q.length - 1]]; return o }
+  const v = get(doc, p)
+  switch (r.int(8)) {
+    case 0: return set(doc, p, r.pick([null, true, 'str', 0, [], {}]))
+    case 1: return p.length ? del(doc, p) : set(doc, p, null)
+    case 2: if (v && typeof v === 'object' && !Array.isArray(v)) { v[`unexpected${r.int(5)}`] = r.pick([1, 'x', null]); return doc } return set(doc, p, 'unexpected')
+    case 3: return set(doc, p, typeof v === 'number' ? r.pick([v * 1000 + 1, -v - 1, v + 0.5, Number.MAX_SAFE_INTEGER, -1]) : -1)
+    case 4: return set(doc, p, typeof v === 'string' ? r.pick(['', v.repeat(40), v + ' ', '😀' + v, v.toUpperCase()]) : '')
+    case 5: if (Array.isArray(v)) { if (v.length && r.chance(0.5)) v.push(clone(v[0])); else v.length = 0; return doc } return set(doc, p, [])
+    case 6: return set(doc, p, typeof v === 'boolean' ? !v : typeof v === 'number' ? String(v) : typeof v === 'string' ? Number(v) || 7 : v)
+    default: return JSON.parse(JSON.stringify(doc).replace(/"([a-zA-Z]+)":/, '"$1_":'))
+  }
+}
+
+// Documents for `schema`: `count` made, half of them with one rule broken.
+function generate (schema, count, seed) {
+  const r = rng(seed)
+  const defs = { $defs: schema && schema.$defs, definitions: schema && schema.definitions }
+  const docs = []
+  for (let i = 0; i < count; i++) {
+    let d = makeValid(schema, r, defs, 0)
+    if (i % 2 === 1 && d !== undefined) d = mutate(clone(d), r)
+    docs.push(d)
+  }
+  return docs
+}
+
+// The project's own documents: a JSON file is one document, a JSON Lines
+// file one per line, a JSON array is taken as one document, not several.
+function readSamples (paths) {
+  const docs = []
+  const files = []
+  for (const p of paths) {
+    if (!fs.existsSync(p)) continue
+    if (fs.statSync(p).isDirectory()) {
+      for (const f of fs.readdirSync(p).sort()) if (/\.(json|jsonl|ndjson)$/.test(f)) files.push(path.join(p, f))
+    } else files.push(p)
+  }
+  for (const f of files) {
+    const text = fs.readFileSync(f, 'utf8')
+    if (/\.(jsonl|ndjson)$/.test(f)) {
+      text.split('\n').forEach((line, i) => { if (line.trim()) { try { docs.push({ source: `${f}:${i + 1}`, doc: JSON.parse(line) }) } catch {} } })
+    } else {
+      try { docs.push({ source: f, doc: JSON.parse(text) }) } catch { docs.push({ source: f, doc: undefined, bad: true }) }
+    }
+  }
+  return docs
+}
+
+function errorKey (e) { return `${e.keyword || ''}@${e.instancePath || ''}` }
+function summarize (result) {
+  if (!result || typeof result !== 'object') return 'no result'
+  const errs = Array.isArray(result.errors) ? result.errors.map(errorKey).sort() : []
+  return `${result.valid ? 'valid' : 'invalid'} ${errs.join(' ')}`
+}
+
+async function loadModule (file) {
+  if (/\.cjs$/.test(file)) { delete require.cache[require.resolve(file)]; return require(file) }
+  return import(pathToFileURL(file).href + `?t=${Date.now()}`)
+}
+
+// Verifies one schema against its module. Returns a report object.
+async function verifyOne ({ schemaFile, moduleFile, schema, generate: count = 200, seed = 1, samples = [] }) {
+  const { Validator } = require('..')
+  const { schemaHash } = require('./schema-hash')
+  const report = { schema: schemaFile, module: moduleFile, documents: 0, generated: 0, samples: 0, valid: 0, agree: 0, disagreements: [], stale: false, missing: false, ataVersion: null, error: null }
+  if (!fs.existsSync(moduleFile)) { report.missing = true; return report }
+  let mod
+  try { mod = await loadModule(moduleFile) } catch (e) { report.error = `module does not load: ${e.message}`; return report }
+  if (typeof mod.isValid !== 'function' || typeof mod.validate !== 'function') { report.error = 'module exports no isValid and validate'; return report }
+  report.ataVersion = mod.ataVersion || null
+  const hash = schemaHash(schema)
+  if (mod.schemaHash !== undefined && mod.schemaHash !== hash) report.stale = true
+  let runtime
+  try { runtime = new Validator(schema, {}) } catch (e) { report.error = `schema does not compile: ${e.message}`; return report }
+  const docs = generate(schema, count, seed).map((d, i) => ({ source: `generated #${i + 1}`, doc: d }))
+  report.generated = docs.length
+  const sampleDocs = readSamples(samples)
+  report.samples = sampleDocs.length
+  for (const { source, doc, bad } of [...docs, ...sampleDocs]) {
+    if (bad || doc === undefined) continue
+    report.documents++
+    const text = JSON.stringify(doc)
+    const a = runtime.validate(JSON.parse(text))
+    const b = mod.validate(JSON.parse(text))
+    const aIs = runtime.isValidObject(JSON.parse(text))
+    const bIs = mod.isValid(JSON.parse(text))
+    if (a.valid) report.valid++
+    const sa = summarize(a), sb = summarize(b)
+    if (sa === sb && aIs === bIs && aIs === a.valid) { report.agree++; continue }
+    if (report.disagreements.length < 20) report.disagreements.push({ source, document: text.length > 400 ? text.slice(0, 400) + '…' : text, runtime: sa, module: sb, runtimeIsValid: aIs, moduleIsValid: bIs })
+    else report.disagreements.push(null)
+  }
+  report.disagreements = report.disagreements.filter(Boolean).concat(report.documents - report.agree > 20 ? [{ more: report.documents - report.agree - 20 }] : [])
+  return report
+}
+
+function renderReport (reports, { json = false } = {}) {
+  if (json) return JSON.stringify({ ok: reports.every(ok), schemas: reports }, null, 2)
+  const lines = []
+  for (const r of reports) {
+    const name = path.relative(process.cwd(), r.schema) || r.schema
+    if (r.missing) { lines.push(`${name}: no module at ${path.relative(process.cwd(), r.module)}; run ata build first`); continue }
+    if (r.error) { lines.push(`${name}: ${r.error}`); continue }
+    const dis = r.documents - r.agree
+    lines.push(`${name}: ${r.documents} documents (${r.generated} generated, ${r.samples} from samples), ${r.valid} valid by the runtime, ${r.agree} agree, ${dis} disagree${r.stale ? '; STALE: the module was built from a different schema' : ''}${r.ataVersion ? ` (module from ata ${r.ataVersion})` : ''}`)
+    for (const d of r.disagreements) {
+      if (d.more) { lines.push(`    ... and ${d.more} more`); continue }
+      lines.push(`    ${d.source}`)
+      lines.push(`      document ${d.document}`)
+      lines.push(`      runtime  ${d.runtime}${d.runtimeIsValid !== (d.runtime.startsWith('valid')) ? ` (isValidObject ${d.runtimeIsValid})` : ''}`)
+      lines.push(`      module   ${d.module}${d.moduleIsValid !== (d.module.startsWith('valid')) ? ` (isValid ${d.moduleIsValid})` : ''}`)
+    }
+  }
+  const bad = reports.filter((r) => !ok(r))
+  lines.push(bad.length === 0
+    ? `ata verify: ${reports.length} schema${reports.length === 1 ? '' : 's'}, every module answers as the runtime does`
+    : `ata verify: ${bad.length} of ${reports.length} schema${reports.length === 1 ? '' : 's'} failed`)
+  return lines.join('\n')
+}
+
+function ok (r) { return !r.missing && !r.error && !r.stale && r.documents === r.agree }
+
+// A module given as source text (a plugin's inlined module) held against the
+// runtime the same way: written to a temporary file, loaded, verified.
+async function verifySource (schema, src, opts = {}) {
+  const os = require('os')
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ata-verify-src-'))
+  const file = path.join(dir, `m.${opts.format === 'cjs' ? 'cjs' : 'mjs'}`)
+  fs.writeFileSync(file, src)
+  try {
+    return await verifyOne({ schemaFile: opts.name || 'schema', moduleFile: file, schema, generate: opts.generate, seed: opts.seed, samples: opts.samples || [] })
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+module.exports = { verifyOne, verifySource, renderReport, generate, mutate, readSamples, ok }

package/lib/version.js

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

package/lite.js

@@ -21,5 +21,6 @@ module.exports = {
   validateAsync: core.validateAsync,
   parseAsync: core.parseAsync,
   defineSchema: core.defineSchema,
+  schemaOf: core.schemaOf,
   version: core.version,
 };

package/lite.mjs

@@ -1,3 +1,3 @@
 import mod from './lite.js';
-export const { Validator, validate, validateAsync, parseAsync, defineSchema, version } = mod;
+export const { Validator, validate, validateAsync, parseAsync, defineSchema, schemaOf, version } = mod;
 export default mod;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.59.0",
+  "version": "1.61.0",
   "description": "JSON Schema validator that compiles to plain JavaScript, still runs where code generation is blocked, and can be compiled away at build time. Passes the full official test suite.",
   "type": "commonjs",
   "main": "index.js",
@@ -88,7 +88,8 @@
     "./lib/native-load.js": "./lib/native-load.browser.js",
     "./lib/aot.js": "./lib/aot.browser.js",
     "./lib/buffer-gate.js": "./lib/buffer-gate.browser.js",
-    "./lib/interpreter.js": "./lib/interpreter.browser.js"
+    "./lib/interpreter.js": "./lib/interpreter.browser.js",
+    "./lib/aot-order.js": false
   },
   "scripts": {
     "prepublishOnly": "node tests/test_pack_purity.js && ATA_ALLOW_DOC_PLACEHOLDERS=1 node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js && node tests/test_safe_regex_embed.js && node tests/test_version_sync.js",
@@ -186,13 +187,13 @@
     "codegen.d.ts"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.59.0",
-    "@ata-validator/native-darwin-x64": "1.59.0",
-    "@ata-validator/native-linux-arm64-gnu": "1.59.0",
-    "@ata-validator/native-linux-arm64-musl": "1.59.0",
-    "@ata-validator/native-linux-x64-gnu": "1.59.0",
-    "@ata-validator/native-linux-x64-musl": "1.59.0",
-    "@ata-validator/native-win32-x64": "1.59.0"
+    "@ata-validator/native-darwin-arm64": "1.61.0",
+    "@ata-validator/native-darwin-x64": "1.61.0",
+    "@ata-validator/native-linux-arm64-gnu": "1.61.0",
+    "@ata-validator/native-linux-arm64-musl": "1.61.0",
+    "@ata-validator/native-linux-x64-gnu": "1.61.0",
+    "@ata-validator/native-linux-x64-musl": "1.61.0",
+    "@ata-validator/native-win32-x64": "1.61.0"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"