ata-validator 1.50.0 → 1.52.0

package/README.md

@@ -138,18 +138,19 @@ errors (7.6M with `richErrors: false`).
 
 | Dimension | Schema | ata-AOT | runtime validator | Difference |
 |---|---|---|---|---|
-| Bundle (gzipped) | simple | 1.4 KB | 52.7 KB | 38.4x smaller |
-| Bundle (gzipped) | complex | 3.0 KB | 52.7 KB | 17.5x smaller |
-| Bundle (gzipped) | nested | 4.5 KB | 52.7 KB | 11.6x smaller |
+| Bundle (gzipped) | simple | 1.3 KB | 52.7 KB | 39.0x smaller |
+| Bundle (gzipped) | complex | 3.0 KB | 52.7 KB | 17.7x smaller |
+| Bundle (gzipped) | nested | 4.5 KB | 52.7 KB | 11.8x smaller |
 | Cold start | simple | 20 ms | 37 ms | 1.9x faster |
-| Throughput (1M ops) | simple | 289 Mops/s | 96 Mops/s | 3.0x faster |
-| Compile time | simple | 18 µs | 1.56 ms | 85x faster |
+| Throughput (1M ops) | simple | 315 Mops/s | 99 Mops/s | 3.2x faster |
+| Compile time | simple | 24 µs | 1.57 ms | 65x faster |
 
 The runtime column is the default validator most frameworks ship. Reproduce on your machine
-with `npm run bench:aot-vs-ajv`. Numbers from one run on Apple M4 Pro, Node 25.2.1, 2026-10-06,
-on ata-validator 1.46.0. Across four runs throughput moved between 288 and 329 Mops/s against
-96 to 116, cold start between 19 and 20 ms against 37 to 39, and the compile ratio between 77x
-and 85x. The throughput row times a single one-million-call
+with `npm run bench:aot-vs-ajv`. Numbers from one run on Apple M4 Pro, Node 25.2.1, 2026-10-11,
+on ata-validator 1.51.0. Across five runs throughput moved between 263 and 325 Mops/s against
+97 to 110, cold start between 20 and 22 ms against 37 to 40, and the compile ratio between 61x
+and 65x. The compile row is the time to write a module, a build-time cost; it was 18 µs on
+1.46.0, and modules have carried the one-pass error function since 1.47.0. The throughput row times a single one-million-call
 loop of a few milliseconds, so it moves the most from run to run; treat the last three rows as
 an order of magnitude rather than a constant.
 
@@ -279,13 +280,13 @@ is the most common way to get a misleading number out of this library.
 
 | | compiled with `ata build` | runtime `new Validator(schema)` |
 |---|---|---|
-| In a bundle, gzipped | **2.1 KB** | 126.1 KB |
+| In a bundle, gzipped | **2.1 KB** | 123.9 KB |
 | Time to a served request | **3.5 ms** | 7.6 ms |
 | Schema known when | build time | any time |
 
 The bundle row is the ten-field user schema in
 `tests/fixtures/error-dx/user.schema.json`, every export of the compiled module against
-`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.48.0.
+`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.51.0.
 The startup row is a Hono route on Bun 1.4, the median of three rounds of best-of-seven, from
 `benchmark/bundle`, against 3.5 ms for the same app doing no validation at all, so the
 compiled path costs nothing measurable to start. The runtime figure is what it is because
@@ -293,7 +294,7 @@ a schema that arrives at run time can use any keyword, so the whole engine has t
 there. The compiled module imports nothing and contains only the checks your schema asks
 for.
 
-**On a server, use whichever fits your schemas.** 113 KB of JavaScript on a Node or Bun
+**On a server, use whichever fits your schemas.** 124 KB of JavaScript on a Node or Bun
 process is not a cost anyone notices, and the runtime API is the simpler thing to reach
 for. Speed is the same either way once warm.
 
@@ -535,7 +536,7 @@ const v = new Validator(schema, {
 
 ### Build-time compile (`ata compile`)
 
-The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. For the ten-field user schema in `tests/fixtures/error-dx/user.schema.json` the module is 2.1 KB gzipped, full error detail included, against 113.3 KB for the runtime bundled for the browser (ata 1.45.0).
+The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. For the ten-field user schema in `tests/fixtures/error-dx/user.schema.json` the module is 2.1 KB gzipped, full error detail included, against 123.9 KB for the runtime bundled for the browser (ata 1.51.0).
 
 ```bash
 npx ata compile schemas/user.json -o src/generated/user.validator.mjs
@@ -581,20 +582,25 @@ error collector out of the modules: each one carries its verdict and its schema,
 its errors from one `ata-errors.mjs` the build writes beside them. The build does this only
 where it makes the output smaller, so a single small schema keeps its self-contained module.
 The errors are the ones `new Validator(schema, { richErrors: false })` reports, in the same
-order. Seven SchemaStore schemas imported into one app, minified with esbuild, go from 148.9 KB
-to 63.3 KB gzipped, and from 35.8 ms to 13.8 ms to import with code generation blocked. A
+order. Forty SchemaStore schemas imported into one app, minified with esbuild, go from 513.8 KB
+to 213.3 KB gzipped, and from 60.4 ms to 28.4 ms to import with code generation blocked. A
 rejected document costs more this way, since its errors come from an interpreted walk:
 `--errors inline` keeps every module self-contained. `--mode schema` writes each module as
 its schema and takes the verdict from the runtime too: forty SchemaStore schemas in one app
-come to 101.6 KB gzipped against 212.6 KB as compact modules, and load and check each once in
-23.0 ms against 35.5, while a check once warm costs about five times what generated code costs.
+come to 102.4 KB gzipped against 213.3 KB as compact modules, and load and check each once in
+23.9 ms against 34.5, while a check once warm costs about five times what generated code costs.
+Schemas that reference each other by `$id` are built against each other, and in schema mode
+they are written once to a shared registry that keeps only the definitions the modules reach;
+`--base-uri <uri>` names files that declare no `$id`. Eight Kubernetes kinds, whose schemas
+share one 1.1 MB definitions file, come to 32.6 KB gzipped as schema modules against 68.6 KB
+self-contained, on ata 1.51.0.
 
 Bundle sizes for the 10-field user schema in `tests/fixtures/error-dx/user.schema.json`,
-minified and gzipped, measured with `bun build --minify --target=browser` on ata 1.45.0:
+minified and gzipped, measured with `bun build --minify --target=browser` on ata 1.51.0:
 
 | What the app imports | Size | Notes |
 |---|---|---|
-| `Validator` from `ata-validator` | 113.3 KB | The compiler ships with it, because a runtime schema can use any keyword |
+| `Validator` from `ata-validator` | 123.9 KB | The compiler ships with it, because a runtime schema can use any keyword |
 | `isValid` from the compiled module | **1.3 KB** | Nothing else is reachable, so the error collector is dropped |
 | `validate` from the compiled module | **1.9 KB** | Adds the detailed error collector |
 
@@ -632,7 +638,7 @@ through a `setFormats()` export the module carries. `docs/API.md` has the
 details.
 
 **Fastify startup, 10 route schemas, from a cold process to the first validated request:
-ajv 19.7 ms, ata 2.75 ms, no build step required.** ata registers in 0.25 ms of that and
+ajv 19.0 ms, ata 2.81 ms, no build step required.** ata registers in 0.20 ms of that and
 compiles on the first request, so counting only registration would overstate the gap.
 Reproduce with `node benchmark/bench_fastify_boot.mjs`.
 

package/aot.d.ts

@@ -56,7 +56,17 @@ export function compactDecline(validator: Validator<unknown>): string | null;
  * runtime Validator does with `richErrors: false`. Null where
  * toCompactModule would be null. `ata build --mode schema` writes these.
  */
-export function toSchemaModule(validator: Validator<unknown>, opts: { runtime: string; format?: 'esm' | 'cjs' }): string | null;
+export function toSchemaModule(validator: Validator<unknown>, opts: { runtime: string; registry?: string; format?: 'esm' | 'cjs' }): string | null;
+
+/**
+ * Source of the registry module schema modules import when their schemas
+ * reference each other by `$id`: the schemas, without descriptive keywords,
+ * as one array. Pass its import specifier as `registry` to toSchemaModule,
+ * for a validator built with those schemas in its `schemas` option; the module
+ * then names its schema by `$id` and carries no copy of it. `ata build --mode
+ * schema` does this for inputs that reference each other.
+ */
+export function registrySource(schemas: ReadonlyArray<object | Validator<unknown>>, format?: 'esm' | 'cjs'): string;
 
 /** Source of the runtime compact modules (and, with `schemaMode`, schema
  * modules) import. With `schemas`, the validators or schemas whose modules

package/aot.mjs

@@ -1,3 +1,3 @@
 import mod from './lib/aot-impl.js';
-export const { toStandalone, toStandaloneModule, toCompactModule, toSchemaModule, compactDecline, errorRuntimeSource, bundle, bundleStandalone, bundleCompact, loadBundle } = mod;
+export const { toStandalone, toStandaloneModule, toCompactModule, toSchemaModule, registrySource, compactDecline, errorRuntimeSource, bundle, bundleStandalone, bundleCompact, loadBundle } = mod;
 export default mod;

package/bin/ata.js

@@ -51,6 +51,9 @@ Build options:
   --mode <mode>           code (default) | schema. schema writes each module as its
                           schema and takes the verdict and errors from one runtime
                           file: far smaller and quicker to load, slower per check
+  --base-uri <uri>        The URI an input without $id is known by: <uri> plus its
+                          file name, for schemas that reference a shared file by URL
+                          or relative path
   --check                 Check (don't write); exit 1 if any output is stale
   --cache-file <path>     Cache file for incremental builds (default: cache disabled)
   --max-size <bytes>      Fail build if any compiled module exceeds this gzipped size
@@ -102,6 +105,7 @@ function parseArgs(argv) {
     if (a === '--one-pass') { out.opts.onePass = true; continue; }
     if (a === '--errors') { out.opts.errors = argv[++i]; continue; }
     if (a === '--mode') { out.opts.mode = argv[++i]; continue; }
+    if (a === '--base-uri') { out.opts.baseUri = argv[++i]; continue; }
     if (a === '--check') { out.opts.check = true; continue; }
     if (a === '--strict') { out.opts.strict = true; continue; }
     if (a === '--strict-schema') { out.opts.strictSchema = true; continue; }
@@ -306,6 +310,7 @@ function cmdBuild(args) {
     onePass: args.opts.onePass === true ? true : undefined,
     errors: args.opts.errors,
     mode: args.opts.mode,
+    baseUri: args.opts.baseUri,
     check: !!args.opts.check,
     maxSize: args.opts.maxSize,
     strict: !!args.opts.strict,
@@ -326,6 +331,22 @@ function cmdBuild(args) {
     }
     if (report.runtime) {
       process.stdout.write(`ata: error runtime -> ${report.runtime.output} (${report.runtime.bytes.toLocaleString()} bytes, shared by the modules above)\n`);
+      if (report.runtime.registry) process.stdout.write(`ata: schema registry -> ${report.runtime.registry.output} (${report.runtime.registry.bytes.toLocaleString()} bytes, the schemas the modules above reference)\n`);
+    }
+    // A module the error generator declined still has an exact verdict, but
+    // every failure is the one ATA9000 error. Said once per module, short,
+    // and once with what to do about it.
+    let noDetail = 0;
+    for (const w of report.warnings || []) {
+      if (w.kind === 'error-detail') {
+        noDetail++;
+        process.stderr.write(`ata: warning ${w.input}: no error detail, failures report the single ATA9000 error (the verdict is exact)\n`);
+      } else {
+        process.stderr.write(`ata: warning ${w.input}: ${w.warning}\n`);
+      }
+    }
+    if (noDetail > 0 && args.opts.mode !== 'schema') {
+      process.stderr.write(`ata: ${noDetail} module${noDetail === 1 ? '' : 's'} without error detail; with --mode schema a module takes its errors from the interpreted engine instead\n`);
     }
     for (const c of report.cached) {
       process.stdout.write(`ata: cached  ${c.input}\n`);

package/index.bundle.mjs

@@ -0,0 +1,15 @@
+// ESM entry for bundlers that target a server (Bun, esbuild or Rollup for
+// Node) and for Node before 22.10, which does not match `module-sync`: the
+// validator core with the code generator registered, as index.js, but with
+// each tool imported on its own (lib/tools.mjs), so the tools an application
+// does not import stay out of its bundle. Through index.js a bundler sees one
+// CommonJS module and keeps all of them.
+import core from './lib/validator-core.js';
+import engine from './lib/codegen-engine.js';
+import { toTypeScript, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON } from './lib/tools.mjs';
+
+core._registerCodegen(engine);
+
+export const { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, defineSchema } = core;
+export { toTypeScript, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON };
+export default { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, toTypeScript, defineSchema, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON };

package/lib/aot-build.js

@@ -109,6 +109,99 @@ function importSpecifier(fromFile, toFile) {
 const RUNTIME_PLACEHOLDER = '__ATA_ERROR_RUNTIME__';
 const ERRORS_MODES = new Set(['auto', 'inline', 'shared']);
 
+// The registry without the definitions no module reaches. A shared
+// definitions file (Kubernetes ships one with hundreds) is mostly what a
+// given set of schemas never uses. Only `definitions` and `$defs` entries are
+// dropped, and only from a document every reference into which is a plain
+// pointer into them; a document reached as a whole, through an anchor, or
+// holding an embedded $id is kept as it is. The result is checked: every
+// root's references must still resolve against it, or the whole registry is
+// kept.
+function pruneRegistry(roots, byId) {
+  const used = new Map();
+  const keepWhole = new Set();
+  const seen = new Set();
+  const queue = [];
+  const hasInnerId = new Map();
+  const innerId = (doc) => {
+    let hit = hasInnerId.get(doc);
+    if (hit !== undefined) return hit;
+    hit = false;
+    const stack = [doc];
+    const visited = new Set();
+    while (stack.length && !hit) {
+      const n = stack.pop();
+      if (n === null || typeof n !== 'object' || visited.has(n)) continue;
+      visited.add(n);
+      if (n !== doc && !Array.isArray(n) && typeof n.$id === 'string') hit = true;
+      for (const k of Object.keys(n)) stack.push(n[k]);
+    }
+    hasInnerId.set(doc, hit);
+    return hit;
+  };
+  const docOf = new Map();
+  for (const [id, doc] of byId) docOf.set(id.replace(/#$/, ''), doc);
+  const reach = (doc, base, node) => {
+    if (node === null || typeof node !== 'object' || seen.has(node)) return;
+    seen.add(node);
+    queue.push([doc, base, node]);
+  };
+  const defsOf = (doc) => (doc.$defs && typeof doc.$defs === 'object' ? '$defs' : doc.definitions && typeof doc.definitions === 'object' ? 'definitions' : null);
+  for (const root of roots) reach(root, typeof root.$id === 'string' ? root.$id : null, root);
+  while (queue.length) {
+    const [doc, base, node] = queue.pop();
+    if (Array.isArray(node)) { for (const x of node) reach(doc, base, x); continue; }
+    for (const k of Object.keys(node)) {
+      const v = node[k];
+      if ((k === '$ref' || k === '$dynamicRef' || k === '$recursiveRef') && typeof v === 'string') {
+        let abs;
+        try { abs = base ? new URL(v, base).href : v.charCodeAt(0) === 35 ? null : new URL(v).href; } catch { abs = null; }
+        const local = v.charCodeAt(0) === 35;
+        const hash = abs === null ? -1 : abs.indexOf('#');
+        const uri = abs === null ? null : hash < 0 ? abs : abs.slice(0, hash);
+        const target = local ? doc : uri !== null ? docOf.get(uri) : undefined;
+        if (target === undefined) continue;
+        const frag = local ? v.slice(1) : hash < 0 ? '' : abs.slice(hash + 1);
+        const tbase = local ? base : uri;
+        const m = /^\/(\$defs|definitions)\/([^/]+)/.exec(frag);
+        const which = defsOf(target);
+        if (k !== '$ref' || m === null || m[1] !== which) {
+          keepWhole.add(target);
+          reach(target, tbase, target);
+          continue;
+        }
+        let name = m[2];
+        try { name = decodeURIComponent(name); } catch {}
+        name = name.replace(/~1/g, '/').replace(/~0/g, '~');
+        let set = used.get(target);
+        if (set === undefined) { set = new Set(); used.set(target, set); }
+        set.add(name);
+        // The rest of the document around its definitions is used too.
+        for (const key of Object.keys(target)) if (key !== which) reach(target, tbase, target[key]);
+        reach(target, tbase, target[which][name]);
+      } else if (v !== null && typeof v === 'object') {
+        reach(doc, base, v);
+      }
+    }
+  }
+  const out = new Map();
+  for (const [id, doc] of byId) {
+    const which = defsOf(doc);
+    if (which === null || keepWhole.has(doc) || innerId(doc) || roots.includes(doc)) { out.set(id, doc); continue; }
+    const names = used.get(doc) || new Set();
+    const defs = {};
+    for (const name of Object.keys(doc[which])) if (names.has(name)) Object.defineProperty(defs, name, { value: doc[which][name], enumerable: true, writable: true, configurable: true });
+    out.set(id, { ...doc, [which]: defs });
+  }
+  for (const root of roots) {
+    if (!aot._refsResolveWithin(root, out)) return byId;
+  }
+  // The registry documents' own references too, as the runtime may walk any
+  // part of a definition it keeps.
+  for (const doc of out.values()) if (!aot._refsResolveWithin(doc, out)) return byId;
+  return out;
+}
+
 async function build(opts) {
   const globs = opts.globs || [];
   if (globs.length === 0) throw new Error('build: at least one glob required');
@@ -138,6 +231,28 @@ async function build(opts) {
   const warnings = [];
   const entries = [];
 
+  // Schemas that reference each other: a schema whose references do not all
+  // land inside it gets the other inputs registered beside it, each under its
+  // $id, or, with `baseUri`, an input without one under the base URI and its
+  // file name. In schema mode its module then resolves against one registry
+  // module the build writes (registrySource); otherwise it is a
+  // self-contained module carrying what it references. A schema that
+  // resolves within itself is built exactly as it would be alone.
+  if (opts.baseUri !== undefined) {
+    try { new URL(opts.baseUri); } catch { throw new Error(`build: baseUri must be an absolute URI (got "${opts.baseUri}")`); }
+  }
+  let siblings = [];
+  for (const input of inputs) {
+    try {
+      const sch = parseSchemaFile(input);
+      if (sch === null || typeof sch !== 'object' || Array.isArray(sch)) continue;
+      if (typeof sch.$id === 'string' && sch.$id !== '') siblings.push({ input, schema: sch });
+      else if (opts.baseUri !== undefined) siblings.push({ input, schema: { $id: new URL(path.basename(input), opts.baseUri).href, ...sch } });
+    } catch {}
+  }
+  if (siblings.length === 0) siblings = null;
+  const REGISTRY_PLACEHOLDER = '__ATA_SCHEMA_REGISTRY__';
+
   const compileOne = (input, raw) => {
     const schema = parseSchemaFile(input);
     // The build is where an authoring mistake is cheapest to stop: a typo
@@ -151,7 +266,13 @@ async function build(opts) {
         return { error: problems.map((x) => `strict mode: ${x.message} at ${x.path}`).join('; ') };
       }
     }
-    const v = new Validator(schema);
+    const needs = siblings !== null && schema !== null && typeof schema === 'object' && !Array.isArray(schema) && !aot._refsResolveWithin(schema);
+    const self = needs ? siblings.find((x) => x.input === input) : undefined;
+    const others = needs ? siblings.filter((x) => x.input !== input && (self === undefined || x.schema.$id !== self.schema.$id)).map((x) => x.schema) : null;
+    // Known under the base URI too, so its own relative references resolve
+    // against it.
+    const own = self !== undefined ? self.schema : schema;
+    const v = others !== null && others.length > 0 ? new Validator(own, { schemas: others }) : new Validator(schema);
     let sourceMap = null;
     if (source) {
       // Only attempt position map for JSON (the scanner is JSON-only).
@@ -174,14 +295,37 @@ async function build(opts) {
       onWarning: (w, meta) => inputWarnings.push({ message: w, kind: (meta && meta.kind) || 'general' }),
     });
     const compact = schemaMode && src
-      ? aot.toSchemaModule(v, { format, runtime: RUNTIME_PLACEHOLDER })
+      ? aot.toSchemaModule(v, others !== null && others.length > 0 ? { format, runtime: RUNTIME_PLACEHOLDER, registry: REGISTRY_PLACEHOLDER } : { format, runtime: RUNTIME_PLACEHOLDER })
       : sharable && src ? aot.toCompactModule(v, { format, formatMode: opts.formatMode, errorRuntime: RUNTIME_PLACEHOLDER }) : null;
     // The runtime parts this module's schema needs (see runtimeFeatures).
-    const features = compact ? require('./error-runtime').runtimeFeatures([require('./schema-strip').stripAnnotations(v._schemaObj)]) : null;
+    // A registry module's schema reaches the others: what it needs from the
+    // registry, by $id, is every schema registered beside it. A key that is
+    // not its schema's $id cannot be found by the runtime, which keys the
+    // registry by $id: such a module is written self-contained.
+    let registryEntries = null;
+    let compactOut = compact;
+    if (compactOut && others !== null && others.length > 0) {
+      // A schema without an $id is not in the registry: its module carries it.
+      registryEntries = typeof v._schemaObj.$id === 'string' ? [v._schemaObj] : [];
+      for (const [id, sub] of v._schemaMap) {
+        if (!sub || typeof sub !== 'object' || sub.$id !== id) { compactOut = null; registryEntries = null; break; }
+        registryEntries.push(sub);
+      }
+    }
+    const { stripAnnotations: _strip } = require('./schema-strip');
+    const features = compactOut ? require('./error-runtime').runtimeFeatures((registryEntries || [v._schemaObj]).map(_strip)) : null;
     // A module that imports the pattern engine needs it in the runtime,
     // whatever the schema scan said.
-    if (features && compact.includes('_ataCompileSafe')) features['safe-regex'] = true;
-    return { schema, src, compact, features, inputWarnings };
+    if (features && compactOut.includes('_ataCompileSafe')) features['safe-regex'] = true;
+    // Why there is no module, when the reason is a reference: which one, and
+    // what would resolve it.
+    let unresolved = null;
+    if (!src) {
+      const miss = {};
+      const registry = v._schemaMap && v._schemaMap.size > 0 ? v._schemaMap : null;
+      if (!aot._refsResolveWithin(v._schemaObj, registry, miss) && typeof miss.ref === 'string') unresolved = miss.ref;
+    }
+    return { schema, src, compact: compactOut, features, registryEntries, root: v._schemaObj, usesSiblings: others !== null, unresolved, inputWarnings };
   };
 
   for (const input of inputs) {
@@ -196,6 +340,9 @@ async function build(opts) {
         cacheEntry.output === output &&
         !!cacheEntry.sharable === sharable &&
         !!cacheEntry.schemaMode === schemaMode &&
+        // A module built against the other inputs depends on them too, and
+        // the registry is put together from such modules: always rebuilt.
+        !cacheEntry.usesSiblings &&
         fs.existsSync(output) &&
         cacheEntry.outputHash === hashContent(fs.readFileSync(output))
       );
@@ -219,13 +366,15 @@ async function build(opts) {
         for (const x of r.inputWarnings) warnings.push({ input, warning: x.message, kind: x.kind });
       }
       if (!r.src) {
-        const reason = 'schema is not AOT-compatible (toStandaloneModule returned null)';
+        const reason = r.unresolved !== null
+          ? `$ref "${r.unresolved}" does not resolve: no input has that $id. Add the schema it names as an input${opts.baseUri === undefined ? ', and if that file has no $id, give it one with --base-uri' : ''}`
+          : 'schema is not AOT-compatible (toStandaloneModule returned null)';
         if (opts.strict) failed.push({ input, error: reason });
         else skipped.push({ input, reason });
         continue;
       }
       entries.push({
-        input, output, raw, inputHash, schema: r.schema, src: r.src, compact: r.compact, features: r.features,
+        input, output, raw, inputHash, schema: r.schema, src: r.src, compact: r.compact, features: r.features, registryEntries: r.registryEntries, root: r.root, usesSiblings: r.usesSiblings,
         fullGz: zlib.gzipSync(r.src).length,
         compactGz: r.compact ? zlib.gzipSync(r.compact).length : null,
       });
@@ -265,6 +414,19 @@ async function build(opts) {
   for (const e of entries) {
     e.mode = runtime !== null && candidates.includes(e) ? (schemaMode ? 'schema' : 'compact') : 'inline';
   }
+  // The registry the schema modules resolve against: every schema any of them
+  // needs, once, by $id.
+  let registryPath = null;
+  let registrySrc = null;
+  if (runtime !== null) {
+    const byId = new Map();
+    for (const e of entries) if (e.mode !== 'inline' && e.registryEntries) for (const sub of e.registryEntries) if (!byId.has(sub.$id)) byId.set(sub.$id, sub);
+    if (byId.size > 0) {
+      registryPath = path.join(path.dirname(runtime.path), 'ata-registry' + (format === 'cjs' ? '.cjs' : '.mjs'));
+      const roots = entries.filter((e) => e.mode !== 'inline' && e.registryEntries).map((e) => e.root);
+      registrySrc = aot.registrySource([...pruneRegistry(roots, byId).values()], format);
+    }
+  }
 
   for (const e of entries) {
     const { input, output } = e;
@@ -282,9 +444,10 @@ async function build(opts) {
         e.schema = r.schema; e.src = r.src; e.compact = r.compact; e.features = r.features;
         if (e.mode !== 'inline' && !r.compact) e.mode = 'inline';
       }
-      const src = e.mode !== 'inline'
+      let src = e.mode !== 'inline'
         ? e.compact.split(JSON.stringify(RUNTIME_PLACEHOLDER)).join(JSON.stringify(importSpecifier(output, runtime.path)))
         : e.src;
+      if (e.mode !== 'inline' && e.registryEntries) src = src.split(JSON.stringify(REGISTRY_PLACEHOLDER)).join(JSON.stringify(importSpecifier(output, registryPath)));
       fs.mkdirSync(path.dirname(output), { recursive: true });
       fs.writeFileSync(output, src);
       const outBytes = Buffer.byteLength(src, 'utf8');
@@ -321,6 +484,7 @@ async function build(opts) {
         fullGz: e.fullGz,
         compactGz: e.compactGz,
         features: e.features || undefined,
+        usesSiblings: e.usesSiblings || undefined,
       };
     } catch (err) {
       failed.push({ input, error: err.message });
@@ -335,11 +499,21 @@ async function build(opts) {
       fs.writeFileSync(runtime.path, runtime.src);
     }
     runtimeReport = { output: runtime.path, bytes: Buffer.byteLength(runtime.src, 'utf8'), gzipBytes: runtime.gz };
+    if (registrySrc !== null) {
+      const cur = fs.existsSync(registryPath) ? fs.readFileSync(registryPath, 'utf8') : null;
+      if (cur !== registrySrc) fs.writeFileSync(registryPath, registrySrc);
+      runtimeReport.registry = { output: registryPath, bytes: Buffer.byteLength(registrySrc, 'utf8'), gzipBytes: zlib.gzipSync(registrySrc).length };
+    }
   }
 
   writeCache(opts.cacheFile, newCache);
 
-  return { compiled, cached, skipped, failed, warnings, runtime: runtimeReport };
+  // The self-contained source is built for every input, so its error-detail
+  // decline is recorded even where the module written is a compact or schema
+  // module, whose errors come from the runtime. Only the written one counts.
+  const fromRuntime = new Set(entries.filter((e) => e.mode !== 'inline').map((e) => e.input));
+  const kept = warnings.filter((w) => !(w.kind === 'error-detail' && fromRuntime.has(w.input)));
+  return { compiled, cached, skipped, failed, warnings: kept, runtime: runtimeReport };
 }
 
 async function watch(opts, onReport) {

package/lib/aot-impl.js

@@ -251,7 +251,7 @@ function onePassCore(validator, opts) {
   const decls = [];
   const args = [];
   const own = new Set();
-  const addOwn = (n) => { if (own.has(n)) return; own.add(n); if (n === '_h' || n === '_hall') addOwn('_hop'); if (n === '_ok') { addOwn('_PN'); addOwn('_hop'); } decls.push(OWN_HELPER_CODE[n]); };
+  const addOwn = (n) => { if (own.has(n)) return; own.add(n); if (n === '_h' || n === '_hall') addOwn('_hop'); if (n === '_ok') { addOwn('_PN'); addOwn('_hop'); } if (n === '_nk') addOwn('_PN'); decls.push(OWN_HELPER_CODE[n]); };
   let usesSafeRe = emit.usesSafeRe, usesCollapse = false;
   for (let i = 0; i < emit.names.length; i++) {
     const name = emit.names[i], val = emit.values[i];
@@ -272,7 +272,7 @@ function onePassCore(validator, opts) {
     if (name === '_VF') { args.push('null'); continue; }
     if (name === '_PN') { addOwn('_PN'); args.push('_PN'); continue; }
     if (name === '_OP' || name === '_gp') { addOwn('_PN'); args.push(name); continue; }
-    if (name === '_hop' || name === '_h' || name === '_ok' || name === '_hall') { addOwn(name); args.push(name); continue; }
+    if (name === '_hop' || name === '_h' || name === '_ok' || name === '_hall' || name === '_nk') { addOwn(name); args.push(name); continue; }
     if (name === '_pe') { decls.push(PTR_ESC_HELPER); args.push('_pe'); continue; }
     if (name === '_deq') { decls.push(DEQ_HELPER); args.push('_deq'); continue; }
     if (name === '_anT') { decls.push('function _anT(){return true}'); args.push('_anT'); continue; }
@@ -687,13 +687,14 @@ function hasRefKey(n, seen) {
   return false;
 }
 
-function refsResolveWithin(schema) {
+// miss: an object that gets `ref`, the first reference that does not resolve.
+function refsResolveWithin(schema, registry, miss) {
   // No reference anywhere (a key of that name inside a value counts too):
   // nothing to resolve, and no index to build.
-  if (!hasRefKey(schema, new Set())) return true;
+  if (!registry && !hasRefKey(schema, new Set())) return true;
   const { indexSchemas, resolveRef } = require('./interpreter-core')._refInternals;
   let state;
-  try { state = indexSchemas(schema, null); } catch { return false; }
+  try { state = indexSchemas(schema, registry || null); } catch { return false; }
   for (const [node, base] of state.nodeBase) {
     if (node === null || typeof node !== 'object') continue;
     for (const k of ['$ref', '$dynamicRef']) {
@@ -701,15 +702,19 @@ function refsResolveWithin(schema) {
       if (r === undefined) continue;
       if (typeof r !== 'string') return false;
       let hit;
-      try { hit = resolveRef(r, base, state); } catch { return false; }
-      if (hit.node === undefined) return false;
+      try { hit = resolveRef(r, base, state); } catch { if (miss) miss.ref = r; return false; }
+      if (hit.node === undefined) { if (miss) miss.ref = r; return false; }
     }
   }
   return true;
 }
 
 const COMPACT_OPTIONS = new Set(['engine', 'strictSchema', 'logger', 'source']);
-function compactDecline(validator) {
+// registryMode: for a schema module that resolves its references against the
+// build's registry (toSchemaModule with `registry`): schemas registered beside
+// the root are allowed, and every reference has to land in the schema or in
+// one of them.
+function compactDecline(validator, registryMode) {
   // Options are allowed by name, not refused by name: one this list does not
   // know (assertFormat: false, baseURI, a future one) may change what the
   // verdict means, and the runtime would not know to follow it.
@@ -718,19 +723,24 @@ function compactDecline(validator) {
   validator._ensureCompiled();
   const o = validator._options || {};
   for (const k of Object.keys(o)) {
-    if (o[k] === undefined || COMPACT_OPTIONS.has(k)) continue;
+    if (o[k] === undefined || COMPACT_OPTIONS.has(k) || (registryMode === true && k === 'schemas')) continue;
     return 'option ' + k;
   }
   if (validator._usesKeywords || validator._externalChecks) return 'custom keywords';
   if (validator._userFormats && Object.keys(validator._userFormats).length) return 'custom formats';
-  if (validator._schemaMap && validator._schemaMap.size > 0) return 'schemas registered beside the root';
+  if (registryMode !== true && validator._schemaMap && validator._schemaMap.size > 0) return 'schemas registered beside the root';
   if (validator._schemaObj === null || typeof validator._schemaObj !== 'object') return 'boolean schema';
   // The runtime has the embedded schema and nothing else: a reference that
   // lands outside it (a meta-schema the runtime Validator resolves from its
   // vendored copies, a schema registered later) would come back unresolved,
   // and the errors with it. The check runs on the schema as embedded.
   const { stripAnnotations } = require('./schema-strip');
-  if (!refsResolveWithin(stripAnnotations(validator._schemaObj))) return 'a reference outside the schema';
+  let registry = null;
+  if (registryMode === true && validator._schemaMap && validator._schemaMap.size > 0) {
+    registry = new Map();
+    for (const [id, sub] of validator._schemaMap) registry.set(id, stripAnnotations(sub));
+  }
+  if (!refsResolveWithin(stripAnnotations(validator._schemaObj), registry)) return registry ? 'a reference outside the schema and the registry' : 'a reference outside the schema';
   return null;
 }
 
@@ -755,7 +765,12 @@ function toCompactModule(validator, opts) {
 function toSchemaModule(validator, opts) {
   assertEmittable(validator, 'toSchemaModule');
   if (!opts || typeof opts.runtime !== 'string') throw new TypeError('toSchemaModule: opts.runtime (the import specifier of the schema runtime) is required');
-  if (compactDecline(validator) !== null) return null;
+  // opts.registry: the import specifier of the build's registry module (the
+  // array of schemas, written by errorRegistrySource), for schemas that
+  // reference each other by $id. The module then names its schema by $id and
+  // carries no copy of it.
+  const registry = typeof opts.registry === 'string' ? opts.registry : null;
+  if (compactDecline(validator, registry !== null) !== null) return null;
   const format = opts.format || 'esm';
   const { stripAnnotations } = require('./schema-strip');
   const { isV1Dialect } = require('./dialect');
@@ -770,12 +785,15 @@ function toSchemaModule(validator, opts) {
     if ('$anchor' in n || '$dynamicAnchor' in n || (!root && '$id' in n)) return false;
     return Object.keys(n).every((k) => flatWalk(n[k], false));
   };
-  const rtOpts = [isV1Dialect(sch) ? 'v1: true' : '', flatWalk(stripped, true) ? 'flat: true' : ''].filter(Boolean).join(', ');
+  const ownId = registry !== null && typeof sch.$id === 'string' ? sch.$id : null;
+  const rtOpts = [isV1Dialect(sch) ? 'v1: true' : '', registry === null && flatWalk(stripped, true) ? 'flat: true' : '', registry !== null ? 'registry: _ataRegistry' : '', ownId !== null ? 'id: ' + JSON.stringify(ownId) : ''].filter(Boolean).join(', ');
   const hashSrc = hashOf(validator);
   const spec = JSON.stringify(opts.runtime);
-  const imp = format === 'esm'
+  const regSpec = registry !== null ? JSON.stringify(registry) : null;
+  const imp = (format === 'esm'
     ? `import { createValidator as _ataCreateValidator } from ${spec};\n`
-    : `const { createValidator: _ataCreateValidator } = require(${spec});\n`;
+    : `const { createValidator: _ataCreateValidator } = require(${spec});\n`)
+    + (regSpec === null ? '' : format === 'esm' ? `import _ataRegistry from ${regSpec};\n` : `const _ataRegistry = require(${regSpec});\n`);
   const exp = format === 'esm'
     ? 'export { validate, isValid, schemaHash, ataVersion };\nexport default { validate, isValid, schemaHash, ataVersion };\n'
     : 'module.exports = { validate, isValid, schemaHash, ataVersion };\nmodule.exports.default = module.exports;\n';
@@ -786,7 +804,7 @@ function toSchemaModule(validator, opts) {
 ${imp}const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
 const ABORT = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ code: 'ATA9000', message: 'validation failed', keyword: '__abort_early__', path: '' })]) });
 let _ataV = null;
-function _ataGet() { return _ataV !== null ? _ataV : (_ataV = _ataCreateValidator(JSON.parse(${text})${rtOpts ? ', { ' + rtOpts + ' }' : ''})); }
+function _ataGet() { return _ataV !== null ? _ataV : (_ataV = _ataCreateValidator(${ownId !== null ? 'null' : 'JSON.parse(' + text + ')'}${rtOpts ? ', { ' + rtOpts + ' }' : ''})); }
 function isValid(data) { return _ataGet().isValid(data); }
 function validate(data) { const v = _ataGet(); if (v.isValid(data)) return VALID; const e = v.errors(data); return e === null ? ABORT : { valid: false, errors: e }; }
 const schemaHash = ${JSON.stringify(hashSrc)};
@@ -794,6 +812,18 @@ const ataVersion = ${JSON.stringify(ATA_VERSION)};
 ${exp}`;
 }
 
+// The registry module schema modules import when their schemas reference each
+// other: every schema of the build, without its descriptive keywords, as one
+// array the runtime turns into its id-to-schema table.
+function registrySource(schemas, format) {
+  const { stripAnnotations } = require('./schema-strip');
+  const text = JSON.stringify(JSON.stringify(schemas.map((x) => stripAnnotations(x && x._schemaObj !== undefined ? x._schemaObj : x)))).replace(/</g, '\\u003c');
+  const head = `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit.\n// The schemas of one build, which its schema modules resolve references against.\n'use strict';\n`;
+  return format === 'cjs'
+    ? head + `module.exports = JSON.parse(${text});\n`
+    : head + `export default JSON.parse(${text});\n`;
+}
+
 // Bundle multiple validators into a single JS file for fast startup.
 // Usage:
 //   const bundle = Validator.bundle([schema1, schema2, ...]);
@@ -1110,6 +1140,7 @@ module.exports = {
   toStandaloneModule: htmlSafeResult(toStandaloneModule),
   toCompactModule: htmlSafeResult(toCompactModule),
   toSchemaModule: htmlSafeResult(toSchemaModule),
+  registrySource: htmlSafeResult(registrySource),
   compactDecline,
   // `schemas`: the validators (or schemas) whose compact modules will import
   // this runtime; parts none of them needs are left out. Omitted, the
@@ -1130,3 +1161,5 @@ module.exports = {
   bundleCompact: htmlSafeResult(bundleCompact),
   loadBundle,
 };
+// For the build only (lib/aot-build.js), not part of ata-validator/aot.
+Object.defineProperty(module.exports, '_refsResolveWithin', { value: refsResolveWithin, enumerable: false });