@json-schema-engine/compiler 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Andrews
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @json-schema-engine/compiler
+
+Compiler tier for JSON Schema: turns a schema registered with `@json-schema-engine/core` into a specialized validator, trampolining to the interpreter for the dynamic islands it cannot emit statically. Add this package once interpreted evaluation shows up in a profile — a compiled artifact is exactly as correct as `Engine.evaluate` and never less complete, so switching tiers is a performance decision, not a semantic one. Needs `@json-schema-engine/core` installed alongside.
+
+## Install
+
+```sh
+npm install @json-schema-engine/compiler @json-schema-engine/core
+```
+
+## Example
+
+```ts
+import assert from "node:assert";
+import { createEngine } from "@json-schema-engine/core";
+import { compileValidator, compileList } from "@json-schema-engine/compiler";
+
+const engine = createEngine();
+const uri = engine.registerSchema(
+  { properties: { name: { type: "string", minLength: 1 } } },
+  "https://example.com/named",
+);
+
+const flag = compileValidator(engine, uri);
+assert.equal(flag.validate({ name: "" }), false);
+assert.equal(flag.validate({ name: "ok" }), true);
+
+const list = compileList(engine, uri);
+const result = list.evaluateList({ name: "" });
+assert.equal(result.valid, false);
+assert.equal(result.errors[0]?.inputLocation, "/name");
+```
+
+## Status
+
+Version 0.0.1 is published for initial public feedback on both the functionality and the documentation. APIs may change before 1.0. [STATUS.md](https://github.com/handrews/json-schema-engine/blob/main/STATUS.md) is the authoritative statement of what is built and what is staged.
+
+## Documentation
+
+- [User guide](https://github.com/handrews/json-schema-engine/blob/main/docs/guide/index.md)
+- [Compiling schemas](https://github.com/handrews/json-schema-engine/blob/main/docs/guide/compiled.md)
+- [Conformance](https://github.com/handrews/json-schema-engine/blob/main/docs/conformance.md)
+- [Repository](https://github.com/handrews/json-schema-engine)
+
+## License
+
+MIT

package/dist/emit.d.ts

@@ -0,0 +1,52 @@
+import type { JsonValue } from "@json-schema-engine/core";
+declare const BRAND: unique symbol;
+/** An opaque, already-escaped fragment of emitted JavaScript. */
+export interface CodeChunk {
+    readonly [BRAND]: true;
+    readonly text: string;
+}
+/**
+ * Tagged template for emitted code. Interpolations MUST be CodeChunks (from
+ * {@link id}/{@link str}/{@link num}/{@link json}/{@link regexTest}/{@link raw}/
+ * {@link frag}); anything else throws, so a stray schema string can never be
+ * spliced verbatim.
+ */
+export declare function js(strings: TemplateStringsArray, ...parts: readonly CodeChunk[]): CodeChunk;
+/**
+ * A machine-generated identifier. NEVER pass schema-derived text here —
+ * identifiers come from the compiler's own counters and a fixed helper
+ * vocabulary. Rejects anything that is not a plain identifier or is reserved.
+ */
+export declare function id(name: string): CodeChunk;
+/** A JavaScript string literal, escaped for embedding (incl. U+2028/U+2029). */
+export declare function str(value: string): CodeChunk;
+/** A numeric literal, JSON-sourced (finite), with an explicit -0 branch. */
+export declare function num(value: number): CodeChunk;
+/**
+ * A JSON constant. Emits an object/array literal only when no nested own key
+ * is `__proto__` (a literal `{"__proto__": …}` sets the prototype in source,
+ * unlike JSON.parse); otherwise routes through a JSON.parse call so the
+ * prototype is never touched.
+ */
+export declare function json(value: JsonValue): CodeChunk;
+/**
+ * A regex membership test against a hoisted, pre-compiled pattern. The
+ * pattern source is escaped as a string literal; the compiled RegExp is
+ * supplied at runtime through the artifact's regex table (never
+ * `RegExp.prototype.toString`, never inline `/…/`).
+ */
+export declare function regexTest(tableRef: CodeChunk, source: string, target: CodeChunk): CodeChunk;
+/** Splice previously built chunks (already escaped). */
+export declare function frag(...chunks: readonly CodeChunk[]): CodeChunk;
+/** Join chunks with a separator (both already escaped). */
+export declare function join(sep: string, chunks: readonly CodeChunk[]): CodeChunk;
+/**
+ * Internal escape hatch for structural code the compiler itself controls
+ * (keywords, operators) — NOT for schema-derived data. Guarded by ESLint so
+ * only emit-internal call sites use it. Kept explicit so audits grep one name.
+ */
+export declare function raw(controlledSource: string): CodeChunk;
+/** The assembled source text of a chunk. */
+export declare const render: (c: CodeChunk) => string;
+export {};
+//# sourceMappingURL=emit.d.ts.map

package/dist/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,QAAA,MAAM,KAAK,eAAsB,CAAC;AAElC,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAOD;;;;;GAKG;AACH,wBAAgB,EAAE,CAChB,OAAO,EAAE,oBAAoB,EAC7B,GAAG,KAAK,EAAE,SAAS,SAAS,EAAE,GAC7B,SAAS,CAYX;AAoDD;;;;GAIG;AACH,wBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAK1C;AAED,gFAAgF;AAChF,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAO5C;AAED,4EAA4E;AAC5E,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAM5C;AAUD;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAgBhD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,SAAS,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,GAChB,SAAS,CAEX;AAED,wDAAwD;AACxD,wBAAgB,IAAI,CAAC,GAAG,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,CAE/D;AAED,2DAA2D;AAC3D,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAEvD;AAED,4CAA4C;AAC5C,eAAO,MAAM,MAAM,GAAI,GAAG,SAAS,KAAG,MAAgB,CAAC"}

package/dist/emit.js

@@ -0,0 +1,166 @@
+// The gated code serializer (D20/M6): the ONLY module that assembles
+// JavaScript source text. Every value that reaches emitted code passes
+// through a typed wrapper here, so schema-derived data is escaped by
+// construction — raw string concatenation of untrusted input is impossible.
+//
+// The `js` tag accepts only CodeChunk arguments (the branded outputs of the
+// wrappers below); a bare string throws. Template static parts are literals
+// by grammar. Downstream modules traffic in CodeChunk, never string, so the
+// type system carries the guarantee and ESLint fences the one escape hatch.
+const BRAND = Symbol("CodeChunk");
+const chunk = (text) => ({ [BRAND]: true, text });
+const isChunk = (v) => typeof v === "object" && v !== null && BRAND in v;
+/**
+ * Tagged template for emitted code. Interpolations MUST be CodeChunks (from
+ * {@link id}/{@link str}/{@link num}/{@link json}/{@link regexTest}/{@link raw}/
+ * {@link frag}); anything else throws, so a stray schema string can never be
+ * spliced verbatim.
+ */
+export function js(strings, ...parts) {
+    let out = strings[0];
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (!isChunk(part)) {
+            throw new TypeError(`js\`\` interpolation ${i} is not a CodeChunk; wrap it (id/str/num/json/…)`);
+        }
+        out += part.text + strings[i + 1];
+    }
+    return chunk(out);
+}
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const RESERVED = new Set([
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "new",
+    "null",
+    "return",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+    "let",
+    "static",
+    "enum",
+    "await",
+    "implements",
+    "package",
+    "protected",
+    "interface",
+    "private",
+    "public",
+]);
+/**
+ * A machine-generated identifier. NEVER pass schema-derived text here —
+ * identifiers come from the compiler's own counters and a fixed helper
+ * vocabulary. Rejects anything that is not a plain identifier or is reserved.
+ */
+export function id(name) {
+    if (!IDENT.test(name) || RESERVED.has(name)) {
+        throw new TypeError(`unsafe identifier '${name}'`);
+    }
+    return chunk(name);
+}
+/** A JavaScript string literal, escaped for embedding (incl. U+2028/U+2029). */
+export function str(value) {
+    const json = JSON.stringify(value);
+    // JSON.stringify leaves U+2028/U+2029 literal; they are valid in JSON but
+    // were line terminators in pre-ES2019 JS and still trip some tooling.
+    return chunk(json.replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029"));
+}
+/** A numeric literal, JSON-sourced (finite), with an explicit -0 branch. */
+export function num(value) {
+    if (!Number.isFinite(value)) {
+        throw new TypeError(`non-finite numeric constant ${String(value)}`);
+    }
+    if (Object.is(value, -0))
+        return chunk("-0");
+    return chunk(String(value));
+}
+/** True when `value` or any nested value is an object with a "__proto__" own key. */
+function hasProtoKey(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return value.some(hasProtoKey);
+    if (Object.hasOwn(value, "__proto__"))
+        return true;
+    return Object.values(value).some(hasProtoKey);
+}
+/**
+ * A JSON constant. Emits an object/array literal only when no nested own key
+ * is `__proto__` (a literal `{"__proto__": …}` sets the prototype in source,
+ * unlike JSON.parse); otherwise routes through a JSON.parse call so the
+ * prototype is never touched.
+ */
+export function json(value) {
+    if (value === null || typeof value !== "object") {
+        if (typeof value === "number")
+            return num(value);
+        if (typeof value === "string")
+            return str(value);
+        return chunk(String(value)); // boolean
+    }
+    if (hasProtoKey(value)) {
+        return chunk(`JSON.parse(${str(JSON.stringify(value)).text})`);
+    }
+    if (Array.isArray(value)) {
+        return chunk(`[${value.map((v) => json(v).text).join(",")}]`);
+    }
+    const members = Object.entries(value).map(([k, v]) => `${str(k).text}:${json(v).text}`);
+    return chunk(`{${members.join(",")}}`);
+}
+/**
+ * A regex membership test against a hoisted, pre-compiled pattern. The
+ * pattern source is escaped as a string literal; the compiled RegExp is
+ * supplied at runtime through the artifact's regex table (never
+ * `RegExp.prototype.toString`, never inline `/…/`).
+ */
+export function regexTest(tableRef, source, target) {
+    return chunk(`${tableRef.text}[${str(source).text}].test(${target.text})`);
+}
+/** Splice previously built chunks (already escaped). */
+export function frag(...chunks) {
+    return chunk(chunks.map((c) => c.text).join(""));
+}
+/** Join chunks with a separator (both already escaped). */
+export function join(sep, chunks) {
+    return chunk(chunks.map((c) => c.text).join(sep));
+}
+/**
+ * Internal escape hatch for structural code the compiler itself controls
+ * (keywords, operators) — NOT for schema-derived data. Guarded by ESLint so
+ * only emit-internal call sites use it. Kept explicit so audits grep one name.
+ */
+export function raw(controlledSource) {
+    return chunk(controlledSource);
+}
+/** The assembled source text of a chunk. */
+export const render = (c) => c.text;
+//# sourceMappingURL=emit.js.map

package/dist/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"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"}

package/dist/explain.d.ts

@@ -0,0 +1,28 @@
+import type { CompilationPlan, FallbackCause } from "./plan.js";
+/** Aggregate view of one {@link CompilationPlan}'s unit classification. */
+export interface CompilationExplanation {
+    /** Every planned unit, static or not. */
+    totalUnits: number;
+    staticUnits: number;
+    interpretedUnits: number;
+    /** Interpreted-unit count per fallback cause; absent cause = zero. */
+    causes: Partial<Record<FallbackCause, number>>;
+    /**
+     * Canonical `baseUri#pointer` keys of the interpreted units — for
+     * diagnosis when a census count assertion fails, not for pinning (key
+     * lists churn on suite reorganization without adding regression signal).
+     */
+    interpretedKeys: string[];
+    /** Units whose apply paths can reach an interpreted unit. */
+    reachesInterpretedCount: number;
+    /**
+     * Static consumer units compiled with runtime evaluated-set tracking (phase
+     * B) — the flag-mode alternative to interpreting a dynamic-coverage consumer.
+     */
+    trackingUnits: number;
+    /** Static units in some tracked unit's in-place coverage region (phase B). */
+    regionUnits: number;
+}
+/** Summarizes a plan's classification for census gates and diagnostics. */
+export declare function explainCompilation(plan: CompilationPlan): CompilationExplanation;
+//# sourceMappingURL=explain.d.ts.map

package/dist/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAEhE,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C;;;;OAIG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,6DAA6D;IAC7D,uBAAuB,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,GACpB,sBAAsB,CA8BxB"}

package/dist/explain.js

@@ -0,0 +1,42 @@
+// Compilation-plan diagnostics (deferred-register item, built for the
+// plan-census gates): interpreted fallback is always CORRECT, so a
+// regression that silently flips units static→interpreted passes every
+// suite/differential/fuzz gate — only a census over these summaries
+// notices. The summarizer is pure read-only projection of plan data.
+/** Summarizes a plan's classification for census gates and diagnostics. */
+export function explainCompilation(plan) {
+    const causes = {};
+    const interpretedKeys = [];
+    let staticUnits = 0;
+    let reachesInterpretedCount = 0;
+    let trackingUnits = 0;
+    let regionUnits = 0;
+    for (const unit of plan.units.values()) {
+        if (unit.kind === "static")
+            staticUnits++;
+        else {
+            interpretedKeys.push(unit.key);
+            if (unit.cause !== undefined) {
+                causes[unit.cause] = (causes[unit.cause] ?? 0) + 1;
+            }
+        }
+        if (unit.reachesInterpreted)
+            reachesInterpretedCount++;
+        if (unit.tracking)
+            trackingUnits++;
+        if (unit.inRegion)
+            regionUnits++;
+    }
+    interpretedKeys.sort();
+    return {
+        totalUnits: plan.units.size,
+        staticUnits,
+        interpretedUnits: plan.units.size - staticUnits,
+        causes,
+        interpretedKeys,
+        reachesInterpretedCount,
+        trackingUnits,
+        regionUnits,
+    };
+}
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,mEAAmE;AACnE,uEAAuE;AACvE,oEAAoE;AACpE,qEAAqE;AA6BrE,2EAA2E;AAC3E,MAAM,UAAU,kBAAkB,CAChC,IAAqB;IAErB,MAAM,MAAM,GAA2C,EAAE,CAAC;IAC1D,MAAM,eAAe,GAAa,EAAE,CAAC;IACrC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,uBAAuB,GAAG,CAAC,CAAC;IAChC,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,WAAW,EAAE,CAAC;aACrC,CAAC;YACJ,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACrD,CAAC;QACH,CAAC;QACD,IAAI,IAAI,CAAC,kBAAkB;YAAE,uBAAuB,EAAE,CAAC;QACvD,IAAI,IAAI,CAAC,QAAQ;YAAE,aAAa,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,QAAQ;YAAE,WAAW,EAAE,CAAC;IACnC,CAAC;IACD,eAAe,CAAC,IAAI,EAAE,CAAC;IACvB,OAAO;QACL,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;QAC3B,WAAW;QACX,gBAAgB,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,WAAW;QAC/C,MAAM;QACN,eAAe;QACf,uBAAuB;QACvB,aAAa;QACb,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+import { type AnnotationSelection, type AnnotationUnit, type BasicOutputDocument, type Engine, type ErrorUnit, type EvaluateOptions, type JsonValue, type ResultFor } from "@json-schema-engine/core";
+import { type CompilationPlan } from "./plan.js";
+import { type CompiledValidate } from "./runtime-compile.js";
+export type { CompilationPlan, PlannedUnit, FallbackCause } from "./plan.js";
+export { buildPlan } from "./plan.js";
+export { explainCompilation } from "./explain.js";
+export type { CompilationExplanation } from "./explain.js";
+export { serializePlan } from "./serialize/index.js";
+export { emitStandalone, StandaloneUnsupportedError } from "./standalone.js";
+export type { StandaloneOptions } from "./standalone.js";
+/** Options for {@link compileValidator}. */
+export interface CompileOptions {
+    /** depth bound shared between compiled nesting and fragments; default core's */
+    maxDepth?: number;
+    /**
+     * Disable the D9 optimizations (inlining, plain-data fast paths). Exists
+     * so the differential fuzzer referees both configurations; not a
+     * user-facing tuning knob.
+     */
+    conservative?: boolean;
+}
+/** Options for {@link compileList}. */
+export interface ListCompileOptions extends CompileOptions {
+    /**
+     * Include `keyword`, `vocabulary`, and structured `params` on each error
+     * unit, matching the interpreter's `errorParams` option on `list` output
+     * (D13).
+     */
+    errorParams?: boolean;
+    /**
+     * Which annotations to collect, matching the interpreter's `annotations`
+     * option: `true` or a selection makes `evaluateList` return an
+     * `annotations` array on valid instances and `basic()` render the Basic
+     * document's annotation side. A selection's allow/deny lists are
+     * specialized into the artifact at compile time; its `keep` predicate runs
+     * at evaluation.
+     */
+    annotations?: boolean | AnnotationSelection;
+}
+/** A compiled list-mode result: interpreter-exact flat error units, plus annotations when collected. */
+export interface CompiledListResult {
+    valid: boolean;
+    errors: ErrorUnit[];
+    /**
+     * Present on valid instances when compiled with `annotations` (absent on
+     * invalid ones, matching `Engine.evaluate`'s valid-only annotation
+     * contract); always absent otherwise.
+     */
+    annotations?: AnnotationUnit[];
+}
+/** A compiled list-mode artifact (see {@link compileList}). */
+export interface CompiledListArtifact {
+    /** evaluate with full error collection ({@link CompiledListResult}) */
+    evaluateList(instance: JsonValue): CompiledListResult;
+    /**
+     * The same result as the Basic document (IETF draft-03 §13.4.2), matching
+     * `Engine.evaluate(uri, x, { output: "basic" }).outputDocument`: the flat
+     * `errors` array on invalid instances; on valid instances compiled with
+     * `annotations`, the selected annotations, present only when non-empty.
+     */
+    basic(instance: JsonValue): BasicOutputDocument;
+    plan: CompilationPlan;
+    source: string;
+}
+/** A compiled artifact: the validator plus its plan and source (inspection/tests). */
+export interface CompiledArtifact {
+    validate: CompiledValidate;
+    plan: CompilationPlan;
+    source: string;
+}
+/**
+ * Options for {@link compileEvaluator}: the flat surface's controls
+ * (`errorParams`, the annotation selection) and the level, fixed when the
+ * evaluator is compiled.
+ */
+export interface EvaluatorCompileOptions extends ListCompileOptions {
+    /**
+     * Retain irrelevant records (draft-03 §12.2) so the artifact can serve
+     * the verbose level: `output: "verbose"`, and `list`/`hierarchical` with
+     * `verbose: true`. A retaining artifact serves the relevant level too;
+     * the retention costs a copy per dropped record and nothing on the
+     * emitted source, which is identical at both levels.
+     */
+    verbose?: boolean;
+}
+/**
+ * The render-time choices of {@link CompiledEvaluator.evaluate}: format,
+ * level, and trace. The controls fixed at compile time are rejected here
+ * with {@link OutputOptionsError} rather than ignored.
+ */
+export type EvaluatorOptions = Pick<EvaluateOptions, "output" | "verbose" | "trace">;
+/**
+ * A compiled evaluator (see {@link compileEvaluator}): every output format
+ * from one recorded application tree, with `Engine.evaluate`'s result for
+ * the same instance and options.
+ */
+export interface CompiledEvaluator {
+    evaluate<O extends EvaluatorOptions>(instance: JsonValue, options?: O): ResultFor<O>;
+    plan: CompilationPlan;
+    source: string;
+}
+/**
+ * Compile a registered schema into a flag-mode validator. The artifact
+ * binds to a snapshot of the engine's schema and dialect registries taken at
+ * compile time, plus the engine's pattern cache: schemas registered,
+ * re-registered, or given a new dialect later are invisible to it, and a
+ * reference unresolved at compile time stays unresolved for it (E1).
+ */
+export declare function compileValidator(engine: Engine, schemaUri: string, options?: CompileOptions): CompiledArtifact;
+/**
+ * Compile a registered schema into a list-output validator (D9e): flat,
+ * interpreter-exact error units — the same elements
+ * `Engine.evaluate(uri, x, { output: "list" }).errors` yields, in the same
+ * order (list artifacts never short-circuit; every branch runs, DESIGN §7).
+ * Error-unit objects materialize only on failure paths. Binds to registry
+ * snapshots exactly like {@link compileValidator}.
+ */
+export declare function compileList(engine: Engine, schemaUri: string, options?: ListCompileOptions): CompiledListArtifact;
+/**
+ * Compile a registered schema into an evaluator that renders every output
+ * format: a list artifact that also records each application's node —
+ * locations, keyword verdicts, and the records it raised — into core's
+ * located tree, so the documents render through the same code as the
+ * interpreter's. Format, level, and `trace` are chosen per evaluation; the
+ * annotation selection, `errorParams`, and whether irrelevant records are
+ * retained (`verbose`) are fixed here (D5). Without retention the records
+ * are discarded at the cut and a verbose-level request throws
+ * {@link OutputOptionsError}. Binds to registry snapshots exactly like
+ * {@link compileValidator}.
+ */
+export declare function compileEvaluator(engine: Engine, schemaUri: string, options?: EvaluatorCompileOptions): CompiledEvaluator;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}