ata-validator 1.61.2 → 1.62.0

package/README.md

@@ -1,6 +1,6 @@
 # ata-validator
 
-JSON Schema validation that compiles for speed and still runs where code generation is blocked. The compiled and interpreted engines answer identically, at 100% of the official suite in both modes, across Draft 2020-12, draft 7 and the [JSON Schema v1 dialect](#dialects). First-class TypeScript inference, and `ata build` emits a standalone module that imports nothing.
+JSON Schema validation where the TypeScript type comes from the schema, or the schema from the type. Write the schema once and `validate` narrows to it; write the type once and the bundler plugin writes its schema in at build time. The compiled and interpreted engines answer identically, at 100% of the official suite in both modes, across Draft 2020-12, 2019-09, drafts 7, 6 and 4 and the [JSON Schema v1 dialect](#dialects), and `ata build` emits a standalone module that imports nothing, with its `.d.mts` beside it.
 
 [![npm](https://img.shields.io/npm/v/ata-validator)](https://www.npmjs.com/package/ata-validator)
 [![License](https://img.shields.io/npm/l/ata-validator)](LICENSE)
@@ -10,6 +10,60 @@ JSON Schema validation that compiles for speed and still runs where code generat
 
 1.0 is a stability commitment: see [docs/STABILITY.md](docs/STABILITY.md) for the semver, deprecation, and error-code guarantees.
 
+## The type and the schema
+
+One source of truth, in either direction. A schema written with `defineSchema` carries its
+type: `validate` narrows `data` to it, and `Infer` pulls the type out for a signature.
+
+```ts
+import { defineSchema, Validator, type Infer } from 'ata-validator'
+
+const User = defineSchema({
+  type: 'object',
+  properties: {
+    id: { type: 'integer', minimum: 1 },
+    email: { type: 'string', format: 'email' },
+    role: { enum: ['admin', 'user'] },
+  },
+  required: ['id', 'email'],
+})
+
+const users = new Validator(User)
+const r = users.validate(JSON.parse(body))
+if (r.valid) {
+  r.data.id    // number
+  r.data.role  // 'admin' | 'user' | undefined
+  r.data.name  // a type error: the schema has no name
+}
+
+type User = Infer<typeof User>
+```
+
+Or start from the type. `schemaOf<T>()` has no run-time form; the bundler plugin reads `T`
+with the TypeScript checker and writes its JSON Schema in place of the call, with the JSDoc
+tags carrying what a type cannot say, and the `new Validator(...)` then compiles away like any
+static schema.
+
+```ts
+import { Validator, schemaOf } from 'ata-validator'
+
+interface Account {
+  /** @minimum 1 */
+  id: number
+  /** @format email */
+  email: string
+  role?: 'admin' | 'user'
+}
+
+const accounts = new Validator(schemaOf<Account>())
+```
+
+`ata build` writes a `.d.mts` next to every compiled module, with the inferred type and an
+`isValid` predicate on it, so a module that imports nothing still narrows. The chainable
+builder in `ata-validator/t`, `Infer` on `anyOf`, `allOf`, tuples and recursive `$ref`, and
+the async `t.refine` are in [Type-safe schemas](#type-safe-schemas); the plugin's type reading
+is in [its README](https://github.com/ata-core/unplugin-ata#a-schema-from-a-typescript-type-schemaofuser).
+
 ## Who uses ata
 
 Projects whose code depends on ata, from GitHub's dependency graph, a framework that lists its
@@ -147,16 +201,24 @@ documents, Node 24:
 
 | | documents a second, the verdict | same, `new Function` refused |
 |---|---:|---:|
-| ata | 3,295,880 | 607,614 |
-| ata, compiled module | 3,319,594 | 3,344,948 |
-| typebox | 1,638,813 | EvalError |
-| ajv | 1,285,492 | EvalError |
-| typia | 939,572 | 964,507 |
-| zod | 440,473 | 237,176 |
-
-Where ata is behind is in the same tables: on a four-field body that fails, ajv answers the
-verdict faster, and with every error read it does 6.6M a second against ata's 2.9M with rich
-errors (7.6M with `richErrors: false`).
+| ata | 3,274,803 | 1,109,881 |
+| ata, compiled module | 3,270,947 | 3,353,351 |
+| typia | 1,957,392 | 1,931,134 |
+| typebox | 1,615,239 | EvalError |
+| ajv | 1,245,508 | EvalError |
+| zod | 436,632 | 230,808 |
+
+Run of 2026-10-30 with typia 15.2.2, which reuses a pattern's RegExp and shortcuts length
+checks after a report from this benchmark; its order figure doubled.
+
+The same repository runs every SchemaStore schema that ships sample documents, 446 of them,
+against the default validator on those samples: ata ahead on 430, median 1.83x, 2.82x on
+schemas of 50 to 200 KB, and never below 0.74x on the 16 where it is behind
+([RESULTS-schemastore.md](https://github.com/ata-core/validator-benchmarks/blob/main/RESULTS-schemastore.md),
+Node 24, ata 1.61.3). Where ata is behind is
+in the same tables: on a four-field body that fails, ajv answers the verdict faster (15.5M
+against 10.4M), and with every error read it does 7.1M a second against ata's 3.6M with rich
+errors, 5.2M with `richErrors: false`.
 
 ## Why AOT
 
@@ -399,31 +461,7 @@ v.countValid(ndjson);        // number
 
 ### Type-safe schemas
 
-ata infers TypeScript types straight from plain JSON Schema. Write the schema once with `defineSchema`, and both runtime validation and the static type come from it, with no builder DSL and no second type declaration to keep in sync.
-
-```ts
-import { defineSchema, Validator } from 'ata-validator'
-
-const userSchema = defineSchema({
-  type: 'object',
-  properties: {
-    id: { type: 'integer', minimum: 1 },
-    role: { type: 'string', enum: ['admin', 'user'] },
-  },
-  required: ['id'],
-})
-
-const v = new Validator(userSchema)
-const result = v.validate(data)
-if (result.valid) {
-  result.data.id   // number
-  result.data.role // 'admin' | 'user' | undefined
-} else {
-  // result.errors: ValidationError[]
-}
-```
-
-`defineSchema` returns the schema untouched at runtime; in TypeScript it gives keyword autocomplete and an error when a value has the wrong shape, with no `as const` needed. `new Validator(schema)` carries the inferred type, so a successful `validate` narrows `result.data` with no manual annotation.
+ata infers TypeScript types straight from plain JSON Schema, as in [the opening example](#the-type-and-the-schema): `defineSchema` returns the schema untouched at runtime and, in TypeScript, gives keyword autocomplete and an error when a value has the wrong shape, with no `as const` needed. `new Validator(schema)` carries the inferred type, so a successful `validate` narrows `result.data` with no manual annotation.
 
 #### Extracting the type: `Infer`
 
@@ -671,7 +709,11 @@ validator only ever called (`v.validate(x)`, `v.isValidObject(x)`), never handed
 it uses the bare wrappers of `ata-validator/compiled-bare` instead, which leave out Standard
 Schema and the extension hook nothing can reach there: 0.3 KB gzipped for both, and
 `ata-validator/compiled-bare-rich` for one that reads ata's own errors. The same form app
-bundles to 10.7 KB gzipped, or 3.1 KB with `richErrors: false` on the validator that reads errors. The errors
+bundles to 10.7 KB gzipped, or 3.1 KB with `richErrors: false` on the validator that reads errors.
+A validator handed only to a Standard Schema consumer the plugin knows (Hono's
+`sValidator`, `hono-openapi`, TanStack Form, oRPC, tRPC, Elysia) takes `ata-validator/compiled-standard`, which
+carries `~standard` alone on a module with plain errors: a Hono route on Cloudflare Workers goes
+from 21.0 to 12.2 KB gzipped, 4.4 KB over Hono by itself. The errors
 then carry `keyword`, `instancePath`, `schemaPath`, `params` and `message`, as that option has
 always given them, without `received`, `suggestion` or `docUrl`.
 
@@ -728,6 +770,86 @@ works as a CI step. This is the check that found the two silent divergences
 fixed in 1.59.0 and 1.60.0, now in a form a project can run on every change.
 It does not run the `.bun.ts` target, which needs Bun's compiler.
 
+### What a schema change does (`ata diff`)
+
+Reading two versions of a schema side by side says which keywords changed. It
+does not say which documents change verdict, and that is the question before
+a deploy: which requests that pass today get a 400 tomorrow. `ata diff` answers
+it with documents:
+
+```bash
+npx ata diff schemas/user.json schemas/user-v2.json --samples test/fixtures
+```
+
+```
+401 documents: 102 accepted by both, 293 rejected by both, 6 rejected only by user-v2.json, 0 accepted only by user-v2.json
+
+Rejected by user-v2.json, accepted by user.json (a client sending these gets a rejection after the change):
+  minimum@/age: 4 documents, 1 of them the project's own, must be >= 18
+    {"email":"kid@example.com","name":"Kid","age":15}  (test/fixtures/signup-teen.json)
+  maxLength@/name: 2 documents, must NOT have more than 40 characters
+    {"email":"a@b.co","name":"abcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghij...
+```
+
+The documents are the ones `ata verify` makes, from both schemas (200 each by
+default, half with one rule broken, then a value on either side of every
+bound), plus the project's own samples. Each one is checked by a `Validator`
+built from each schema, and the ones that change verdict are grouped by the
+rule that decides them, with one example each, the project's own document
+when there is one. The exit code is 1 when a document the old schema accepts
+is rejected by the new one, so a pull request that tightens a schema fails
+the check until someone looks. Generated documents are a sample, not a proof:
+a change this reports is real, one it does not report may still exist.
+
+### Validation as the body arrives
+
+A request that carries many documents, a JSON array or NDJSON, is usually read to the end,
+parsed as a whole and then validated, so a bad third record is reported after the last byte.
+`ata-validator/stream` validates each record the moment its last byte lands and stops reading
+at the first failure, with memory that does not grow with the body.
+
+```js
+import { validateStream } from 'ata-validator/stream'
+
+app.post('/orders/import', async (c) => {
+  const r = await validateStream(orders, c.req.raw.body)   // a Web ReadableStream, or a Node Readable
+  if (!r.valid) return c.json({ record: r.errors[0].record, errors: r.errors[0].errors }, 400)
+  return c.json({ imported: r.records })
+})
+```
+
+`v.stream(opts)` on Node, or `streamValidator(v, opts)` from `ata-validator/stream` anywhere (the lite, edge and browser entries do not carry the method, so their bundles stay what they were), is the same thing fed by hand: `push(chunk)` takes strings or bytes and returns
+the first failure as soon as its record is complete, `end()` returns `{ valid, records, errors }`.
+`onRecord(doc, index)` hands over each record that passed, parsed, so an import does not parse
+twice; `stopOnFirst: false` lists every failing record instead of stopping. The format is read
+from the first character (`[` is an array, anything else NDJSON) or set with `format`. A JSON
+array is split by a scan that tracks strings and nesting, not by parsing it, so the elements are
+parsed one at a time.
+
+Measured on a 100 MB body of 128,419 order documents, read in 64 KB chunks, Node 25, Apple M4
+Pro, one process per row:
+
+| | invalid record 3 | invalid last record |
+|---|---|---|
+| read it all, `JSON.parse`, validate the array | 517 ms, 783 MB | 571 ms, 845 MB |
+| read it all, split lines, parse and validate each | 237 ms, 553 MB | 462 ms, 660 MB |
+| `ata-validator/stream`, JSON array | 13.5 ms, 122 MB, 0.1 MB read | 577 ms, 195 MB |
+| `ata-validator/stream`, NDJSON | 19.6 ms, 122 MB, 0.1 MB read | 461 ms, 197 MB |
+
+Peak RSS; the 100 MB figure is the process without the body. A body that is valid to the end
+costs the same time as before and a third of the memory. `tests/test_stream.js` holds the stream
+to whole-document validation under every way of cutting the bytes into chunks, including inside
+multi-byte characters, strings with brackets and escaped quotes, nested arrays, scalars, CRLF
+and blank lines, and checks that a failing source is destroyed or cancelled rather than read on.
+
+A Node http request handed to `validateStream` is not destroyed at the failure: closing the
+socket under the response turns the answer into a network error at the client (Node's `fetch`
+uploading 100 MB got `write EPIPE`, Chrome "Failed to fetch", neither the 400). Reading stops and
+the rest of the body is read and dropped, so the response goes out and memory stays flat. Node's
+`fetch` then had the 400 after 24 ms and 1 MB sent; Chrome, which reads only after its upload,
+after 58 ms for a 50 MB file over loopback; the Hono example above, whose Node adapter cancels
+the stream without closing the socket, after 28 ms. A plain `Readable` is still destroyed.
+
 ### Bun, compiled ahead of time
 
 Bun's ahead-of-time compiler (`bun build --compile --aot`, an open pull

package/bin/ata.js

@@ -15,6 +15,8 @@ Usage:
   ata migrate  [dir]         [options]  Report what switching from ajv would change; --write applies it.
   ata verify   <glob>...     [options]  Check that each schema's compiled module answers as the runtime
                                         does, on generated documents and the project's samples.
+  ata diff     <old> <new>   [options]  What a change to a schema does: the documents the old schema
+                                        accepts and the new one rejects, and the reverse, by rule.
 
 Verify options:
   --generate <n>          Documents made from each schema, half with one rule broken. Default: 200
@@ -23,6 +25,13 @@ Verify options:
   --json                  Report as JSON
   --out-dir, --suffix, --format    Where the modules are, as given to ata build
 
+Diff options:
+  --generate <n>          Documents made from each schema. Default: 200
+  --samples <path>        The project's own documents, checked too (repeatable)
+  --seed <n>              Seed for the generated documents. Default: 1
+  --json                  Report as JSON
+  Exit status 1 when a document the old schema accepts is rejected by the new one.
+
 Validate options:
   --pretty                Render errors with source frames (default on TTY)
   --compact               Render errors as one line each (default when piped)
@@ -487,6 +496,24 @@ function cmdVerify (args) {
   })().catch((e) => { process.stderr.write(`error: ${e.message}\n`); process.exit(1); });
 }
 
+function cmdDiff (args) {
+  if (args._.length < 2) {
+    process.stderr.write('error: ata diff <old-schema> <new-schema>\n');
+    process.exit(2);
+  }
+  const buildLib = require('../lib/aot-build');
+  const { diffSchemas, renderDiff, breaking } = require('../lib/schema-diff');
+  let oldSchema, newSchema;
+  try { oldSchema = buildLib.parseSchemaFile(args._[0]); newSchema = buildLib.parseSchemaFile(args._[1]); } catch (e) { process.stderr.write(`error: ${e.message}\n`); process.exit(2); }
+  const samples = args.opts.samples === undefined ? [] : [].concat(args.opts.samples);
+  let report;
+  try {
+    report = diffSchemas(oldSchema, newSchema, { generate: Number.isFinite(args.opts.generate) ? args.opts.generate : 200, seed: Number.isFinite(args.opts.seed) ? args.opts.seed : 1, samples });
+  } catch (e) { process.stderr.write(`error: ${e.message}\n`); process.exit(2); }
+  process.stdout.write(renderDiff(report, { json: !!args.opts.json, oldName: path.basename(args._[0]), newName: path.basename(args._[1]) }) + '\n');
+  process.exit(breaking(report) ? 1 : 0);
+}
+
 function cmdValidate (args) {
   if (args._.length < 2) {
     process.stderr.write('error: ata validate <schema> <data-file>\n');
@@ -506,7 +533,8 @@ function cmdValidate (args) {
   try {
     schema = JSON.parse(schemaContent);
   } catch (e) {
-    process.stderr.write(`error: ${schemaPath} is not valid JSON: ${e.message}\n`);
+    // The parser quotes the text it stopped at, and the text is the file's.
+    process.stderr.write(`error: ${schemaPath} is not valid JSON: ${require('../lib/diagnose').term(e.message)}\n`);
     process.exit(2);
   }
 
@@ -523,7 +551,7 @@ function cmdValidate (args) {
   try {
     v = new Validator(schema, { source: { path: schemaPath, content: schemaContent } });
   } catch (e) {
-    process.stderr.write(`error: schema compile failed: ${e.message}\n`);
+    process.stderr.write(`error: schema compile failed: ${require('../lib/diagnose').term(e.message)}\n`);
     process.exit(2);
   }
 
@@ -592,6 +620,11 @@ function main() {
     return;
   }
 
+  if (cmd === 'diff') {
+    cmdDiff(args);
+    return;
+  }
+
   if (cmd === 'migrate') {
     const { migrate, formatReport } = require('../lib/migrate');
     const result = migrate(args._[0] || '.', { write: !!args.opts.write });

package/compat.js

@@ -129,7 +129,9 @@ class Ata {
     const formatNames = Object.keys(this._formats);
     if (formatNames.length > 0) out.formats = { ...this._formats };
     const keywordNames = Object.keys(this._keywords);
-    const kws = {};
+    // Null prototype: a keyword named __proto__ written into a plain object
+    // would set its prototype and never reach the validator.
+    const kws = Object.create(null);
     for (const name of keywordNames) if (this._keywords[name] !== true) kws[name] = this._keywords[name];
     if (Object.keys(kws).length > 0) out.keywords = kws;
     const registry = this._registrySnapshot();
@@ -646,8 +648,16 @@ function referencedDefaults(rootDoc, registry) {
     }
     return node;
   };
+  // `done`, per call: the schemas already applied to each object. A second
+  // application fills nothing new, and following every edge of a chain such
+  // as n_i = allOf [n_(i-1), n_(i-1)] applied the bottom schema 2^n times.
+  let done = null;
   const fill = (schema, data, active) => {
     if (schema === null || typeof schema !== 'object' || data === null || typeof data !== 'object' || active.has(schema)) return;
+    let applied = done.get(data);
+    if (applied === undefined) done.set(data, (applied = new Set()));
+    if (applied.has(schema)) return;
+    applied.add(schema);
     active.add(schema);
     if (typeof schema.$ref === 'string') fill(resolve(schema.$ref), data, active);
     if (Array.isArray(schema.allOf)) for (const sub of schema.allOf) fill(sub, data, active);
@@ -670,7 +680,10 @@ function referencedDefaults(rootDoc, registry) {
     }
     active.delete(schema);
   };
-  return (data) => fill(rootDoc, data, new Set());
+  return (data) => {
+    done = new Map();
+    try { fill(rootDoc, data, new Set()); } finally { done = null; }
+  };
 }
 
 // The registry id a fragment-only key is kept under: a `#...` string is not an

package/compiled-standard.d.ts

@@ -0,0 +1,6 @@
+// ata-validator/compiled-standard: the compiled-module wrapper for a validator
+// a bundler plugin sees handed to Standard Schema consumers only.
+import type { StandardSchemaV1Props } from './index.js';
+import type { CompiledModule } from './compiled.js';
+
+export function bareStandard<T = unknown>(mod: CompiledModule, schema: object | boolean, useDefaults?: boolean): { '~standard': StandardSchemaV1Props<T> };

package/compiled-standard.mjs

@@ -0,0 +1,66 @@
+// ata-validator/compiled-standard as an ES module of its own, not a re-export
+// of the CommonJS file, so a bundler adds no interop code (see
+// compiled-bare.mjs). The same `~standard` as lib/compiled-standard.js builds
+// through lib/standard-schema.js; tests/test_compiled_standard.js holds the
+// two to the same issues and the same schema documents.
+
+// When the module's error function answers valid where its verdict said no,
+// the disagreement is reported rather than turned into an acceptance.
+const DISAGREES = [{ message: 'schema validation failed', instancePath: '' }];
+const EMPTY_PATH = Object.freeze([]);
+
+// A JSON pointer as a Standard Schema path: an all-digit segment without a
+// leading zero is an array index and comes out as a number.
+function pathOf(pointer) {
+  if (!pointer) return EMPTY_PATH;
+  const out = [];
+  for (const raw of pointer.split('/').slice(1)) {
+    const seg = raw.indexOf('~') >= 0 ? raw.replace(/~1/g, '/').replace(/~0/g, '~') : raw;
+    out.push({ key: /^(?:0|[1-9][0-9]*)$/.test(seg) ? Number(seg) : seg });
+  }
+  return Object.freeze(out);
+}
+
+// Standard JSON Schema: the document, as a copy, for its own dialect.
+function jsonSchemaOf(schema) {
+  const convert = (options) => {
+    const target = options && options.target;
+    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 });
+}
+
+export function bareStandard(mod, schema, useDefaults) {
+  const fill = useDefaults !== false && typeof mod.applyDefaults === 'function' ? mod.applyDefaults : null;
+  const isValid = mod.isValid;
+  const errFn = mod.validate;
+  return {
+    '~standard': Object.freeze({
+      version: 1,
+      vendor: 'ata-validator',
+      jsonSchema: jsonSchemaOf(schema),
+      validate(value) {
+        if (fill !== null) fill(value);
+        if (isValid(value)) return { value };
+        const r = errFn(value);
+        const errors = r && r.valid === false ? r.errors : DISAGREES;
+        const issues = new Array(errors.length);
+        for (let i = 0; i < errors.length; i++) {
+          const e = errors[i];
+          issues[i] = { message: e.message || 'validation failed', path: pathOf(e.instancePath != null ? e.instancePath : (e.path || '')) };
+        }
+        return { issues };
+      },
+    }),
+  };
+}
+
+export default { bareStandard };

package/index.d.ts

@@ -509,6 +509,13 @@ export interface Validator<T = unknown> {
   /** Validate a JSON string. Uses simdjson fast path for large documents. */
   validateJSON(jsonString: string): ValidationResult<T>;
 
+  /**
+   * Validation as the body arrives: a record stream over this validator for a
+   * JSON array or NDJSON fed in chunks, reporting the first failing record the
+   * moment it is complete. See `ata-validator/stream` for the types.
+   */
+  stream(opts?: import('./stream').StreamOptions): import('./stream').RecordStream;
+
   /** Fast boolean check for a JSON string */
   isValidJSON(jsonString: string): boolean;
 

package/index.js

@@ -6,6 +6,16 @@
 // lib/codegen-engine.js, so that the edge entry (index.edge.js) and
 // ata-validator/lite can load the core without it.
 const core = require('./lib/validator-core.js');
+
+// Validation as the body arrives: `v.stream(opts)` is a record stream over the
+// validator (lib/stream.js), loaded on first use. Defined here, on the Node
+// entry, and not in the core: the lite, edge and browser builds are measured
+// to the byte and a static require from the core would put the stream into
+// every one of them; there `ata-validator/stream` is imported where it is used.
+Object.defineProperty(core.Validator.prototype, 'stream', {
+  configurable: true, writable: true,
+  value: function stream (opts) { return require('./lib/stream.js').streamValidator(this, opts); },
+});
 // The code generator loads on first need, or once the event loop is free,
 // not with the package: it is most of what requiring the package parsed. The
 // timer is unref'd, so a script that has finished does not stay to load it.

package/lib/aot-build.js

@@ -95,7 +95,13 @@ function runtimePathFor(outputs, opts, format) {
   let dir = path.resolve(path.dirname(outputs[0]));
   for (const o of outputs) {
     const d = path.resolve(path.dirname(o));
-    while (dir !== d && !d.startsWith(dir + path.sep)) dir = path.dirname(dir);
+    // The root already ends in a separator ('/' or a drive root), and dirname of the
+    // root is the root: compared against root + sep the walk never ended.
+    while (dir !== d && !d.startsWith(dir.endsWith(path.sep) ? dir : dir + path.sep)) {
+      const up = path.dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
   }
   return path.join(dir, name);
 }
@@ -245,6 +251,15 @@ async function buildWith(opts) {
   // check once warm.
   if (opts.mode !== undefined && opts.mode !== 'code' && opts.mode !== 'schema') throw new Error(`build: mode must be code or schema (got "${opts.mode}")`);
   const schemaMode = opts.mode === 'schema' && !opts.abortEarly;
+  // The options that change what a module holds, recorded with each cache
+  // entry and required to match. Without them a module built for production
+  // (no schema-source frames) was reported up to date by a development build
+  // and kept, since the input and the output had not changed.
+  const optionsKey = JSON.stringify([
+    !!opts.abortEarly, opts.onePass === true, !!opts.plainErrors, !!opts.verdictOnly,
+    opts.order === undefined ? null : opts.order, opts.formatMode === undefined ? null : opts.formatMode,
+    opts.baseUri === undefined ? null : opts.baseUri, opts.target === undefined ? null : opts.target, !!opts.types,
+  ]);
 
   const compiled = [];
   const cached = [];
@@ -367,6 +382,8 @@ async function buildWith(opts) {
         cacheEntry.output === output &&
         !!cacheEntry.sharable === sharable &&
         !!cacheEntry.schemaMode === schemaMode &&
+        cacheEntry.source === source &&
+        cacheEntry.options === optionsKey &&
         // A module built against the other inputs depends on them too, and
         // the registry is put together from such modules: always rebuilt.
         !cacheEntry.usesSiblings &&
@@ -522,6 +539,8 @@ async function buildWith(opts) {
         outputHash: hashContent(Buffer.from(src, 'utf8')),
         sharable,
         schemaMode,
+        source,
+        options: optionsKey,
         mode: e.mode,
         runtime: e.mode !== 'inline' ? runtime.path : undefined,
         fullGz: e.fullGz,
@@ -577,8 +596,13 @@ async function watch(opts, onReport) {
     }
   };
 
+  // The build writes its cache file, JSON and often beside the schemas; a
+  // change to it is the build's own and starts nothing, or every build woke
+  // the watcher for the next one.
+  const cachePath = opts.cacheFile ? path.resolve(opts.cacheFile) : null;
   const watchers = dirs.map((d) => fs.watch(d, (_event, filename) => {
     if (!filename) return;
+    if (cachePath !== null && path.resolve(d, filename) === cachePath) return;
     const ext = path.extname(filename).toLowerCase();
     if (ext !== '.json' && ext !== '.yaml' && ext !== '.yml') return;
     if (debounceTimer) clearTimeout(debounceTimer);
@@ -754,3 +778,5 @@ module.exports = {
   toStandaloneModule,
   schemaHash,
 };
+// For tests only, not part of ata-validator/build.
+Object.defineProperty(module.exports, '_runtimePathFor', { value: runtimePathFor, enumerable: false });