ata-validator 1.49.0 → 1.50.0

package/lib/aot-build.js

@@ -87,19 +87,102 @@ function hashContent(buf) {
   return crypto.createHash('sha256').update(buf).digest('hex').slice(0, 32);
 }
 
+// Where the shared error runtime goes: the output directory when there is
+// one, otherwise the deepest directory that holds every output.
+function runtimePathFor(outputs, opts, format) {
+  const name = 'ata-errors' + (format === 'cjs' ? '.cjs' : '.mjs');
+  if (opts.outDir) return path.join(opts.outDir, name);
+  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);
+  }
+  return path.join(dir, name);
+}
+
+function importSpecifier(fromFile, toFile) {
+  let rel = path.relative(path.dirname(path.resolve(fromFile)), path.resolve(toFile)).split(path.sep).join('/');
+  if (!rel.startsWith('.')) rel = './' + rel;
+  return rel;
+}
+
+const RUNTIME_PLACEHOLDER = '__ATA_ERROR_RUNTIME__';
+const ERRORS_MODES = new Set(['auto', 'inline', 'shared']);
+
 async function build(opts) {
   const globs = opts.globs || [];
   if (globs.length === 0) throw new Error('build: at least one glob required');
   const format = opts.format || 'esm';
+  const errorsMode = opts.errors || 'auto';
+  if (!ERRORS_MODES.has(errorsMode)) throw new Error(`build: errors must be auto, inline or shared (got "${errorsMode}")`);
   const inputs = await expandGlobs(globs);
   const cache = readCache(opts.cacheFile);
   const newCache = {};
+  const source = resolveSourceDefault(opts);
+  // Error detail from the shared runtime replaces generated error code, so it
+  // is only on offer where that code is what the build would emit: not with
+  // schema-source frames (development builds), stub errors or the one-pass
+  // function, which are each asked for by name.
+  const sharable = errorsMode !== 'inline' && !source && !opts.abortEarly && opts.onePass !== true;
+  // `mode: 'schema'`, asked for by name: every module that can be is a schema
+  // module (its schema and a few lines), with the verdict and the errors from
+  // one runtime. Smaller and quicker to load than generated code, slower per
+  // 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;
 
   const compiled = [];
   const cached = [];
   const skipped = [];
   const failed = [];
   const warnings = [];
+  const entries = [];
+
+  const compileOne = (input, raw) => {
+    const schema = parseSchemaFile(input);
+    // The build is where an authoring mistake is cheapest to stop: a typo
+    // like maxLenght compiles into a validator that simply lacks the rule,
+    // and a compiled module fails even more quietly than a runtime one,
+    // since nobody ever revisits it. Findings fail the input's build.
+    if (opts.strictSchema) {
+      const { checkSchemaStrict } = require('./strict-check');
+      const problems = checkSchemaStrict(schema, {});
+      if (problems.length > 0) {
+        return { error: problems.map((x) => `strict mode: ${x.message} at ${x.path}`).join('; ') };
+      }
+    }
+    const v = new Validator(schema);
+    let sourceMap = null;
+    if (source) {
+      // Only attempt position map for JSON (the scanner is JSON-only).
+      const ext = path.extname(input).toLowerCase();
+      if (ext === '.json') {
+        try { sourceMap = buildPositionMap(raw.toString('utf8')); }
+        catch { sourceMap = null; }
+      }
+    }
+    const schemaFile = path.relative(process.cwd(), input) || input;
+    const inputWarnings = [];
+    const src = aot.toStandaloneModule(v, {
+      format,
+      abortEarly: !!opts.abortEarly,
+      onePass: opts.onePass === true ? true : undefined,
+      source,
+      sourceMap,
+      schemaFile,
+      formatMode: opts.formatMode,
+      onWarning: (w, meta) => inputWarnings.push({ message: w, kind: (meta && meta.kind) || 'general' }),
+    });
+    const compact = schemaMode && src
+      ? aot.toSchemaModule(v, { 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 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 };
+  };
 
   for (const input of inputs) {
     try {
@@ -107,100 +190,119 @@ async function build(opts) {
       const inputHash = hashContent(raw);
       const output = outputPathFor(input, { ...opts, format });
       const cacheEntry = cache[input];
-      if (opts.check) {
-        const upToDate = (
-          cacheEntry &&
-          cacheEntry.inputHash === inputHash &&
-          cacheEntry.output === output &&
-          fs.existsSync(output) &&
-          cacheEntry.outputHash === hashContent(fs.readFileSync(output))
-        );
-        if (upToDate) {
-          cached.push({ input, output });
-        }
-        continue;
-      }
-      if (
+      const fresh = !!(
         cacheEntry &&
         cacheEntry.inputHash === inputHash &&
         cacheEntry.output === output &&
+        !!cacheEntry.sharable === sharable &&
+        !!cacheEntry.schemaMode === schemaMode &&
         fs.existsSync(output) &&
         cacheEntry.outputHash === hashContent(fs.readFileSync(output))
-      ) {
-        cached.push({ input, output });
-        newCache[input] = cacheEntry;
+      );
+      if (opts.check) {
+        if (fresh) cached.push({ input, output });
         continue;
       }
-      const schema = parseSchemaFile(input);
-      // The build is where an authoring mistake is cheapest to stop: a typo
-      // like maxLenght compiles into a validator that simply lacks the rule,
-      // and a compiled module fails even more quietly than a runtime one,
-      // since nobody ever revisits it. Findings fail the input's build.
-      if (opts.strictSchema) {
-        const { checkSchemaStrict } = require('./strict-check');
-        const problems = checkSchemaStrict(schema, {});
-        if (problems.length > 0) {
-          failed.push({ input, error: problems.map((x) => `strict mode: ${x.message} at ${x.path}`).join('; ') });
-          continue;
-        }
-      }
-      const v = new Validator(schema);
-      const source = resolveSourceDefault(opts);
-      let sourceMap = null;
-      if (source) {
-        // Only attempt position map for JSON (the scanner is JSON-only).
-        const ext = path.extname(input).toLowerCase();
-        if (ext === '.json') {
-          try { sourceMap = buildPositionMap(raw.toString('utf8')); }
-          catch { sourceMap = null; }
-        }
+      if (fresh) {
+        entries.push({ input, output, raw, inputHash, cacheEntry, fullGz: cacheEntry.fullGz, compactGz: cacheEntry.compactGz, features: cacheEntry.features || null });
+        continue;
       }
-      const schemaFile = path.relative(process.cwd(), input) || input;
-      const inputWarnings = [];
-      const src = aot.toStandaloneModule(v, {
-        format,
-        abortEarly: !!opts.abortEarly,
-        onePass: opts.onePass === true ? true : undefined,
-        source,
-        sourceMap,
-        schemaFile,
-        formatMode: opts.formatMode,
-        onWarning: (w, meta) => inputWarnings.push({ message: w, kind: (meta && meta.kind) || 'general' }),
-      });
-      if (inputWarnings.length > 0) {
+      const r = compileOne(input, raw);
+      if (r.error) { failed.push({ input, error: r.error }); continue; }
+      if (r.inputWarnings.length > 0) {
         if (opts.strict) {
-          failed.push({ input, error: inputWarnings.map((x) => x.message).join('; ') });
+          failed.push({ input, error: r.inputWarnings.map((x) => x.message).join('; ') });
           continue;
         }
         // `kind` says which capability degraded ('error-detail', 'parse'),
         // so a caller that requested both can tell the warnings apart.
-        for (const x of inputWarnings) warnings.push({ input, warning: x.message, kind: x.kind });
+        for (const x of r.inputWarnings) warnings.push({ input, warning: x.message, kind: x.kind });
       }
-      if (!src) {
+      if (!r.src) {
         const reason = '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,
+        fullGz: zlib.gzipSync(r.src).length,
+        compactGz: r.compact ? zlib.gzipSync(r.compact).length : null,
+      });
+    } catch (e) {
+      failed.push({ input, error: e.message });
+    }
+  }
+
+  if (opts.check) {
+    const staleCount = inputs.length - cached.length;
+    return { compiled: [], cached, skipped, failed, warnings, staleCount };
+  }
+
+  // A module takes its errors from the shared runtime when that makes it
+  // smaller, and the runtime is written when the modules that use it save
+  // more than it weighs. With `errors: 'shared'` every module that can, does.
+  // The runtime carries only the parts the compact modules' schemas need
+  // (formats, the pattern engine, deep equality); an entry with no record of
+  // its needs (a cache written before this) counts as needing everything.
+  const { errorRuntimeSource, runtimeFeatures } = require('./error-runtime');
+  const ATA_VERSION = require('./version');
+  const unionOf = (list) => {
+    const out = runtimeFeatures([]);
+    for (const e of list) for (const k of Object.keys(out)) if (!e.features || e.features[k]) out[k] = true;
+    return out;
+  };
+  const candidates = entries.filter((e) => typeof e.compactGz === 'number' && (schemaMode || errorsMode === 'shared' || e.compactGz < e.fullGz));
+  let runtime = null;
+  if ((sharable || schemaMode) && candidates.length > 0) {
+    const runtimeSrc = errorRuntimeSource(format, ATA_VERSION, unionOf(candidates), schemaMode);
+    const runtimeGz = zlib.gzipSync(runtimeSrc).length;
+    let saving = 0;
+    for (const e of candidates) saving += e.fullGz - e.compactGz;
+    const use = schemaMode || errorsMode === 'shared' || saving > runtimeGz;
+    if (use) runtime = { path: runtimePathFor(entries.map((e) => e.output), opts, format), src: runtimeSrc, gz: runtimeGz };
+  }
+  for (const e of entries) {
+    e.mode = runtime !== null && candidates.includes(e) ? (schemaMode ? 'schema' : 'compact') : 'inline';
+  }
+
+  for (const e of entries) {
+    const { input, output } = e;
+    try {
+      if (e.cacheEntry) {
+        const sameRuntime = e.mode === 'inline' || (runtime !== null && e.cacheEntry.runtime === runtime.path);
+        if (e.cacheEntry.mode === e.mode && sameRuntime) {
+          cached.push({ input, output });
+          newCache[input] = e.cacheEntry;
+          continue;
+        }
+        // The build's choice for this module changed: compile it again.
+        const r = compileOne(input, e.raw);
+        if (r.error || !r.src) { failed.push({ input, error: r.error || 'schema is not AOT-compatible' }); continue; }
+        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'
+        ? e.compact.split(JSON.stringify(RUNTIME_PLACEHOLDER)).join(JSON.stringify(importSpecifier(output, runtime.path)))
+        : e.src;
       fs.mkdirSync(path.dirname(output), { recursive: true });
       fs.writeFileSync(output, src);
       const outBytes = Buffer.byteLength(src, 'utf8');
-      const gz = zlib.gzipSync(src);
-      const gzBytes = gz.length;
+      const gzBytes = zlib.gzipSync(src).length;
       if (typeof opts.maxSize === 'number' && gzBytes > opts.maxSize) {
         // Roll back the write so a failed build doesn't leave a stale artifact.
         try { fs.unlinkSync(output); } catch {}
         failed.push({ input, error: `output ${output} exceeds --max-size: ${gzBytes} > ${opts.maxSize} (gzipped bytes)` });
         continue;
       }
-      compiled.push({ input, output, bytes: outBytes, gzipBytes: gzBytes });
+      compiled.push({ input, output, bytes: outBytes, gzipBytes: gzBytes, errors: e.mode });
       if (opts.types !== false) {
         const { toTypeScript } = require('./ts-gen');
         const stem = path.basename(input, path.extname(input)).replace(/\.schema$/, '');
         const typeName = stem
           .replace(/[^A-Za-z0-9_]/g, '_')
           .replace(/^([a-z])/, (m) => m.toUpperCase()) || 'Data';
-        const dts = toTypeScript(schema, { name: typeName });
+        const dts = toTypeScript(e.schema, { name: typeName });
         const ext = path.extname(output);
         const dtsExt = ext === '.mjs' ? '.d.mts'
           : ext === '.cjs' ? '.d.cts'
@@ -209,23 +311,35 @@ async function build(opts) {
         fs.writeFileSync(base + dtsExt, dts);
       }
       newCache[input] = {
-        inputHash,
+        inputHash: e.inputHash,
         output,
         outputHash: hashContent(Buffer.from(src, 'utf8')),
+        sharable,
+        schemaMode,
+        mode: e.mode,
+        runtime: e.mode !== 'inline' ? runtime.path : undefined,
+        fullGz: e.fullGz,
+        compactGz: e.compactGz,
+        features: e.features || undefined,
       };
-    } catch (e) {
-      failed.push({ input, error: e.message });
+    } catch (err) {
+      failed.push({ input, error: err.message });
     }
   }
 
-  if (opts.check) {
-    const staleCount = inputs.length - cached.length;
-    return { compiled: [], cached, skipped, failed, warnings, staleCount };
+  let runtimeReport = null;
+  if (runtime !== null && entries.some((e) => e.mode !== 'inline')) {
+    const current = fs.existsSync(runtime.path) ? fs.readFileSync(runtime.path, 'utf8') : null;
+    if (current !== runtime.src) {
+      fs.mkdirSync(path.dirname(runtime.path), { recursive: true });
+      fs.writeFileSync(runtime.path, runtime.src);
+    }
+    runtimeReport = { output: runtime.path, bytes: Buffer.byteLength(runtime.src, 'utf8'), gzipBytes: runtime.gz };
   }
 
   writeCache(opts.cacheFile, newCache);
 
-  return { compiled, cached, skipped, failed, warnings };
+  return { compiled, cached, skipped, failed, warnings, runtime: runtimeReport };
 }
 
 async function watch(opts, onReport) {
@@ -322,12 +436,41 @@ function compiledSchemaFor(schema) {
 // error function the generator declines (unevaluated* among them), where the
 // module would report every failure as the ATA9000 stub while the runtime
 // reports the real errors.
+//
+// With `errorRuntime` (an import specifier, usually 'ata-validator/error-runtime'),
+// the module is written compact where the validator allows it: the verdict and
+// the schema, with errors from that runtime (see toCompactModule). A plugin
+// writes it in place of the self-contained module when that is smaller for
+// the whole bundle; the runtime is shared by every compact module in it.
+// A plugin asks for both modules of one schema (the self-contained one, and
+// the compact one to compare): one Validator answers both, so the verdict
+// function compiles once. Keyed by the schema object the plugin passes.
+const _validators = new WeakMap();
+function validatorFor(schema) {
+  let v = _validators.get(schema);
+  // Built with an options object, empty, so it stays out of the identity
+  // cache: `new Validator(schema)` in the caller's own code must get its own
+  // instance, not this compiled one.
+  if (v === undefined) { v = new Validator(schema, {}); _validators.set(schema, v); }
+  return v;
+}
+
 function compiledModuleFor(schema, opts) {
   if (!compiledEligible(schema)) return null;
+  if (opts && typeof opts.errorRuntime === 'string') {
+    try {
+      const v = validatorFor(schema);
+      const src = aot.toCompactModule(v, { format: opts.format || 'esm', errorRuntime: opts.errorRuntime });
+      if (src) return src;
+    } catch {
+      return null;
+    }
+    // Not writable as a compact module: the self-contained one below.
+  }
   let degraded = false;
   let src;
   try {
-    src = toStandaloneModule(schema, {
+    src = aot.toStandaloneModule(validatorFor(schema), {
       format: (opts && opts.format) || 'esm',
       onWarning: (msg, info) => { if (info && info.kind === 'error-detail') degraded = true; },
     });

package/lib/aot-impl.js

@@ -352,7 +352,10 @@ function toStandaloneModule(validator, opts) {
   const jsFn = validator._jsFn;
   if (!jsFn || !jsFn._source) return null;
   const format = (opts && opts.format) || 'esm';
-  const abortEarly = !!(opts && opts.abortEarly);
+  // A compact module (toCompactModule) carries the verdict and its schema, and
+  // takes its errors from the shared runtime at this import specifier.
+  const errorRuntime = opts && typeof opts._errorRuntime === 'string' ? opts._errorRuntime : null;
+  const abortEarly = !!(opts && opts.abortEarly) || errorRuntime !== null;
   const source = !!(opts && opts.source);
   const sourceMap = opts && opts.sourceMap ? opts.sourceMap : null;
   const schemaFile = opts && opts.schemaFile ? opts.schemaFile : null;
@@ -488,7 +491,43 @@ function toStandaloneModule(validator, opts) {
   const fmt = emitFormatDecls(jsFn._formatClosures, opts && opts.formatMode, 'const');
   const formatDecls = fmt.decls;
 
-  const validBody = onePass !== null
+  // A compact module takes the linear-time pattern engine from the runtime,
+  // which carries it anyway, instead of embedding a copy (2.9 KB gzipped,
+  // minified) in every module that has a pattern the platform RegExp does not
+  // run.
+  const usesSafeRe = errorRuntime !== null && ((jsFn && jsFn._usesSafeRe) || (jsErrFn && jsErrFn._usesSafeRe));
+  let compactCore = '';
+  if (errorRuntime !== null) {
+    const { stripAnnotations } = require('./schema-strip');
+    const { isV1Dialect } = require('./dialect');
+    const sch = typeof validator._schemaObj === 'object' ? validator._schemaObj : validator._schemaObj;
+    // Embedded as JSON text and parsed: a literal would turn a "__proto__"
+    // key into the object's prototype, and V8 reads JSON faster than an
+    // object literal of the same size.
+    const text = JSON.stringify(JSON.stringify(stripAnnotations(sch))).replace(/</g, '\\u003c');
+    const v1 = sch !== null && typeof sch === 'object' && isV1Dialect(sch);
+    // No embedded resource and no anchor anywhere (a key of that name inside
+    // a value counts too): the runtime can skip indexing the schema.
+    const flat = (() => {
+      const seen = new Set();
+      const walk = (n, root) => {
+        if (n === null || typeof n !== 'object' || seen.has(n)) return true;
+        seen.add(n);
+        if (Array.isArray(n)) return n.every((x) => walk(x, false));
+        if ('$anchor' in n || '$dynamicAnchor' in n || (!root && '$id' in n)) return false;
+        return Object.keys(n).every((k) => walk(n[k], false));
+      };
+      return walk(stripAnnotations(sch), true);
+    })();
+    const rtOpts = [v1 ? 'v1: true' : '', flat ? 'flat: true' : ''].filter(Boolean).join(', ');
+    // Nothing of it runs at import: the schema is parsed and the runtime
+    // set up on the first rejected document whose errors are read, so a
+    // module that only accepts costs no more to load than its verdict.
+    compactCore = `let _ataErrs = null;\nfunction _ataErrors(d) { if (_ataErrs === null) _ataErrs = _ataCreateErrors(JSON.parse(${text})${rtOpts ? ', { ' + rtOpts + ' }' : ''}); return _ataErrs(d); }\n`;
+  }
+  const validBody = errorRuntime !== null
+    ? 'if (_fn(data)) return VALID; const e = _ataErrors(data); return e === null ? ABORT : { valid: false, errors: e }'
+    : onePass !== null
     ? 'return _vC(data)'
     : errCore
       ? 'return _fn(data) ? VALID : { valid: false, errors: errFn(data, true).errors }'
@@ -565,7 +604,7 @@ function validateJSON(text) {
   // schema as the caller wrote it (before dialect normalization), so a build
   // can compare it against schemaHash(currentSchema) and know the module is
   // stale without embedding its own fingerprint.
-  const hashSrc = schemaHash(validator._rawSchema !== undefined ? validator._rawSchema : validator._schemaObj);
+  const hashSrc = hashOf(validator);
   // The schema hash answers "is this module built from a different schema" and
   // nothing else. Upgrading ata and not re-running the generate step leaves the
   // hash matching, so the stale module reads as current. The module cannot ask
@@ -589,11 +628,11 @@ function validateJSON(text) {
     degradedNote += '// NOTE: parse() was requested but could not be generated for this schema;\n// the module has no parse export. Validate and strip with the runtime Validator.\n';
   }
   return `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit.
-// Schema is embedded; runtime has zero dependency on ata-validator.
+${errorRuntime === null ? '// Schema is embedded; runtime has zero dependency on ata-validator.' : '// Compact module: the verdict and the schema; errors come from the runtime it imports.'}
 // Re-run the build after upgrading ata: the version above is what wrote this.
 ${degradedNote}'use strict';
-${_CP_LEN_SOURCE}
-${safeRePrelude(jsFn, jsErrFn, onePass !== null && onePass.usesSafeRe ? { _usesSafeRe: true } : null)}${schemaSourceConst}const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
+${errorRuntime === null ? '' : format === 'esm' ? `import { createErrors as _ataCreateErrors${usesSafeRe ? ', compileSafe as _ataCompileSafe' : ''} } from ${JSON.stringify(errorRuntime)};\n` : `const { createErrors: _ataCreateErrors${usesSafeRe ? ', compileSafe: _ataCompileSafe' : ''} } = require(${JSON.stringify(errorRuntime)});\n`}${_CP_LEN_SOURCE}
+${errorRuntime !== null ? (usesSafeRe ? 'const __ataSafeRe = _ataCompileSafe;\n' : '') : safeRePrelude(jsFn, jsErrFn, onePass !== null && onePass.usesSafeRe ? { _usesSafeRe: true } : null)}${schemaSourceConst}const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
 const ABORT = Object.freeze({
   valid: false,
   errors: Object.freeze([Object.freeze({
@@ -606,11 +645,155 @@ const ABORT = Object.freeze({
 ${closureDecls}${sharedBlock}${preambleDecls}${formatDecls}const _fn = function(d) {
   ${src}
 };
-${errCore}function isValid(data) { return _fn(data); }
+${errCore}${compactCore}function isValid(data) { return _fn(data); }
 function validate(data) { ${validBody}; }
 ${parseCore}${positionsCore}${hashDecl}${exports}`;
 }
 
+// Why a validator cannot be written as a compact module, or null when it can.
+// The error runtime walks the embedded schema with the interpreted engine and
+// knows nothing the schema does not say, so anything the validator adds from
+// outside the schema keeps the module self-contained.
+// The error runtime's generator reads the library's own files with fs, and
+// runs in Node only (ata build, errorRuntimeSource). It is required through a
+// name rather than a literal so that a bundler following this module, in a
+// build of the package for a runtime without fs, does not try to bring fs
+// along: 1.49.0 bundled for such runtimes, and the generator must not break
+// that.
+const ERROR_RUNTIME_MODULE = './error-runtime';
+function loadErrorRuntime() { return require(ERROR_RUNTIME_MODULE); }
+
+// The schema hash a module stamps, once per validator: a plugin writes both
+// modules of a schema (self-contained and compact) from one validator, and
+// hashing a large schema canonically is not free.
+const _hashes = new WeakMap();
+function hashOf(validator) {
+  let h = _hashes.get(validator);
+  if (h === undefined) {
+    h = schemaHash(validator._rawSchema !== undefined ? validator._rawSchema : validator._schemaObj);
+    _hashes.set(validator, h);
+  }
+  return h;
+}
+
+// True when every $ref and $dynamicRef in the schema resolves inside it, by
+// the interpreter's own resolver.
+function hasRefKey(n, seen) {
+  if (n === null || typeof n !== 'object' || seen.has(n)) return false;
+  seen.add(n);
+  if (Array.isArray(n)) { for (const x of n) if (hasRefKey(x, seen)) return true; return false; }
+  if ('$ref' in n || '$dynamicRef' in n) return true;
+  for (const k of Object.keys(n)) if (hasRefKey(n[k], seen)) return true;
+  return false;
+}
+
+function refsResolveWithin(schema) {
+  // 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;
+  const { indexSchemas, resolveRef } = require('./interpreter-core')._refInternals;
+  let state;
+  try { state = indexSchemas(schema, null); } catch { return false; }
+  for (const [node, base] of state.nodeBase) {
+    if (node === null || typeof node !== 'object') continue;
+    for (const k of ['$ref', '$dynamicRef']) {
+      const r = node[k];
+      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;
+    }
+  }
+  return true;
+}
+
+const COMPACT_OPTIONS = new Set(['engine', 'strictSchema', 'logger', 'source']);
+function compactDecline(validator) {
+  // 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.
+  // What the validator registers beside its schema (a meta-schema it
+  // resolves, for one) is known only once it has compiled.
+  validator._ensureCompiled();
+  const o = validator._options || {};
+  for (const k of Object.keys(o)) {
+    if (o[k] === undefined || COMPACT_OPTIONS.has(k)) 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 (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';
+  return null;
+}
+
+// A module that carries its verdict and its schema without the descriptive
+// keywords, and imports its errors from the shared runtime at `errorRuntime`
+// (written beside it by the build, see errorRuntimeSource). Null when the
+// validator cannot be written this way; the caller writes the
+// self-contained module instead.
+function toCompactModule(validator, opts) {
+  assertEmittable(validator, 'toCompactModule');
+  if (!opts || typeof opts.errorRuntime !== 'string') throw new TypeError('toCompactModule: opts.errorRuntime (the import specifier of the error runtime) is required');
+  if (compactDecline(validator) !== null) return null;
+  return toStandaloneModule(validator, { format: opts.format, formatMode: opts.formatMode, _errorRuntime: opts.errorRuntime });
+}
+
+// A schema module: the schema without its descriptive keywords and a few lines
+// that hand it to the runtime at `opts.runtime`, which answers both the
+// verdict and the errors with the interpreted engine. Smaller and quicker to
+// load than generated code, slower per check once warm (about five times on
+// SchemaStore documents). Answers as toCompactModule's module does. Null
+// where toCompactModule would be null.
+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;
+  const format = opts.format || 'esm';
+  const { stripAnnotations } = require('./schema-strip');
+  const { isV1Dialect } = require('./dialect');
+  const sch = validator._schemaObj;
+  const stripped = stripAnnotations(sch);
+  const text = JSON.stringify(JSON.stringify(stripped)).replace(/</g, '\\u003c');
+  const seen = new Set();
+  const flatWalk = (n, root) => {
+    if (n === null || typeof n !== 'object' || seen.has(n)) return true;
+    seen.add(n);
+    if (Array.isArray(n)) return n.every((x) => flatWalk(x, false));
+    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 hashSrc = hashOf(validator);
+  const spec = JSON.stringify(opts.runtime);
+  const imp = format === 'esm'
+    ? `import { createValidator as _ataCreateValidator } from ${spec};\n`
+    : `const { createValidator: _ataCreateValidator } = require(${spec});\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';
+  return `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit.
+// Schema module: the schema; the verdict and the errors come from the runtime it imports.
+// Re-run the build after upgrading ata: the version above is what wrote this.
+'use strict';
+${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 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)};
+const ataVersion = ${JSON.stringify(ATA_VERSION)};
+${exp}`;
+}
+
 // Bundle multiple validators into a single JS file for fast startup.
 // Usage:
 //   const bundle = Validator.bundle([schema1, schema2, ...]);
@@ -925,6 +1108,23 @@ const htmlSafeResult = (fn) => function () { return htmlSafe(fn.apply(this, argu
 module.exports = {
   toStandalone: htmlSafeResult(toStandalone),
   toStandaloneModule: htmlSafeResult(toStandaloneModule),
+  toCompactModule: htmlSafeResult(toCompactModule),
+  toSchemaModule: htmlSafeResult(toSchemaModule),
+  compactDecline,
+  // `schemas`: the validators (or schemas) whose compact modules will import
+  // this runtime; parts none of them needs are left out. Omitted, the
+  // runtime carries every part.
+  // `schemaMode`: the runtime schema modules import, which also answers the
+  // verdict (createValidator).
+  errorRuntimeSource: htmlSafeResult((format, schemas, schemaMode) => {
+    const er = loadErrorRuntime();
+    if (!Array.isArray(schemas)) return er.errorRuntimeSource(format, ATA_VERSION, undefined, !!schemaMode);
+    const { stripAnnotations } = require('./schema-strip');
+    const embedded = schemas.map((x) => stripAnnotations(x && typeof x === 'object' && x._schemaObj !== undefined ? x._schemaObj : x));
+    const features = er.runtimeFeatures(embedded);
+    for (const x of schemas) if (x && x._jsFn && x._jsFn._usesSafeRe) features['safe-regex'] = true;
+    return er.errorRuntimeSource(format, ATA_VERSION, features, !!schemaMode);
+  }),
   bundle: htmlSafeResult(bundle),
   bundleStandalone: htmlSafeResult(bundleStandalone),
   bundleCompact: htmlSafeResult(bundleCompact),