json-schema-engine 0.0.2__tar.gz → 0.0.3__tar.gz

{json_schema_engine-0.0.2 → json_schema_engine-0.0.3}/CHANGELOG.md

@@ -5,7 +5,37 @@ format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versions follow [SemVer](https://semver.org/) with the 0.x caveat that
 minor versions may change public API.
 
-## [0.0.2] - unreleased
+## [0.0.3] - 2026-09-21
+
+### Added
+
+- `compile_evaluator`: compiles a registered root schema into an evaluator
+  serving every output format the interpreter does (errors, annotations,
+  dropped records, the application trace), not only the verdict `flag`
+  level.
+- Plan-time resolution of `$dynamicRef`/`$recursiveRef`: a reference site
+  whose target is the same on every path that can reach it compiles as an
+  ordinary static edge instead of falling back to the interpreter;
+  `explain_compilation` reports such sites through `resolved_dynamic_sites`.
+- Runtime coverage tracking: an `unevaluated*` consumer whose evaluated
+  coverage depends on runtime branching (an `anyOf`/`oneOf` alternative, an
+  `if`'s condition) compiles directly instead of islanding, folding a
+  runtime coverage channel instead of a static licence.
+- Public `json_schema_engine.core.lowering`: the compiler lowering IR a
+  custom keyword's `lower()` is built from, previously private to the
+  engine's own keyword modules.
+
+### Changed
+
+- `first_duplicate_pair` returns a list.
+- Compiled error messages now match the interpreter's for `oneOf`,
+  `contains`, `uniqueItems`, and `type`.
+- A dialect refusing unknown keywords no longer compiles those units
+  silently: an unknown keyword under such a dialect now falls back to the
+  interpreter like any other unlowerable case, rather than being planned
+  as if the keyword were absent.
+
+## [0.0.2] - 2026-09-21
 
 The first functional release. Everything below is new relative to the
 0.0.1 name reservation.

{json_schema_engine-0.0.2 → json_schema_engine-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: json-schema-engine
-Version: 0.0.2
+Version: 0.0.3
 Summary: A spec-complete, annotation-first JSON Schema engine for Python: interpreter, compiler, formats, every standard output format.
 Project-URL: Homepage, https://github.com/handrews/py-json-schema-engine
 Project-URL: Repository, https://github.com/handrews/py-json-schema-engine
@@ -39,20 +39,16 @@ relevance model.
 
 Produced by Henry Andrews via Claude Code.
 
-**Status: `0.0.2` is the first functional release.**
+**Status: `0.0.3` is fully compliant except for draft-04 support.**
+
+See [CHANGELOG.md](CHANGELOG.md) for the current release's contents.
+[DESIGN.md](DESIGN.md) is the design contract and carries the milestone
+status.
 
 All `0.0.x` releases will have AI-written documentation.  Version
 `0.1.0` will indicate that the documentation has been audited and revised
 by a human.
 
-As of `0.0.2`, this package carries the
-interpreter core for 2020-12, 2019-09, draft-07, and draft-06 with every
-standard output format, the compiler tier (a flag validator and standalone
-modules, M6–M7), and the `json_schema_engine.formats` package — green on
-every official test-suite file for those drafts through both tiers, on the
-official output-tests, and on Bowtie. [DESIGN.md](DESIGN.md) is the design
-contract and carries the milestone status.
-
 The regular-expression translator lives in its own package,
 [`ecma-regex`](packages/ecma-regex/README.md) (`0.1.0`): ECMA-262 patterns
 for Python, with JavaScript semantics, no dependency on this engine.
@@ -93,12 +89,14 @@ one. Each keeps its own semantics, so a draft-07 `$ref` ignores its
 siblings while a 2019-09 one does not.
 
 Every standard output format is available by name: `flag` (the default),
-`basic`, `detailed`, and `verbose` from the IETF draft-03 output spec, and
-`list` and `hierarchical` from the machines-oriented proposal. Annotations
-are a separate control (`annotations=True`, or an `AnnotationSelection`),
-`verbose=True` asks `list`/`hierarchical` for the verbose level with
-irrelevant records marked as dropped, and `trace=True` adds the application
-tree with error indexes into `result.errors`.
+`basic`, `detailed`, and `verbose` from the
+[IETF working group draft-03](https://www.ietf.org/archive/id/draft-ietf-jsonschema-json-schema-03.html)
+output sections, and `list` and `hierarchical` from the
+[machines-oriented proposal](https://github.com/json-schema-org/json-schema-spec/blob/main/specs/output/jsonschema-validation-output-machines.md).
+Annotations are a separate control (`annotations=True`, or an
+`AnnotationSelection`), `verbose=True` asks `list`/`hierarchical` for the
+verbose level with irrelevant records marked as dropped, and `trace=True`
+adds the application tree with error indexes into `result.errors`.
 
 ```python
 result = engine.evaluate(uri, {"name": 3}, output="hierarchical")
@@ -129,9 +127,9 @@ attach a `source` location to every error and annotation, and
 ## Compile
 
 The compiler tier turns a registered schema into a Python function. It is
-not a second implementation: any subschema it cannot emit (a `$dynamicRef`,
-an `unevaluated*` whose coverage is only known at runtime, an in-place
-cycle) calls back into the interpreter, so a compiled validator is exactly
+not a second implementation: any subschema it cannot emit (a `$dynamicRef`
+whose target differs by path, an in-place cycle) calls back into the
+interpreter, so a compiled validator is exactly
 as correct as `Engine.evaluate` and never less complete. Tier choice is a
 performance decision, not a semantic one.
 
@@ -154,9 +152,25 @@ only the standard library and this package's pure helpers; it refuses,
 with `StandaloneUnsupportedError`, a schema that would need the
 interpreter at evaluation time. Compiled code assumes plain data as
 `json.loads` produces it (`dict`, `list`, `str`, `int`, `float`, `bool`,
-`None`); subclasses of those types belong to the interpreter. Errors,
-annotations, and the output formats are interpreter features today;
-compiled output beyond the verdict is a later milestone.
+`None`); subclasses of those types belong to the interpreter.
+
+`compile_evaluator` compiles a schema into an evaluator serving every
+output format the interpreter does — errors, annotations, dropped
+records, and the application trace, not only the verdict. The annotation
+selection is fixed at compile time; every other control (`output`,
+`error_params`, `verbose`, `trace`, `positions`) is chosen per call, same
+as `Engine.evaluate`.
+
+```python
+from json_schema_engine.compiler import compile_evaluator
+
+evaluator = compile_evaluator(engine, uri, annotations=True)
+compiled_result = evaluator.evaluate({}, output="list", error_params=True)
+interpreted_result = engine.evaluate(
+    uri, {}, output="list", error_params=True, annotations=True
+)
+assert compiled_result.errors == interpreted_result.errors
+```
 
 ## Formats
 
@@ -258,10 +272,6 @@ large arrays of distinct values do not incur quadratic cost, while genuine
 duplicates — including numbers equal across `int`/`float` and objects that
 differ only in member order — are still reported.
 
-**No prototype hazard.** Python dicts have no prototype chain, so there is
-nothing for a hostile property name to pollute: `__proto__`, `constructor`,
-and similar reserved-looking names evaluate as ordinary properties.
-
 ## Development
 
 ```sh
@@ -290,21 +300,26 @@ uv run python scripts/bowtie_check.py
 uv run python scripts/bench.py --budget-ms 250 --filter user
 ```
 
-`scripts/bench.py` times the compiler tier's flag and standalone artifacts
-against the interpreter and two competitors (fastjsonschema, jsonschema)
-over seven corpora in `packages/bench`: three small hand-authored schemas,
-the official OpenAPI 3.1 schema against a real document, a generated
-API-payload corpus, and two 2000-record corpora. It is report-only (it
-enforces no performance threshold) and, per the IP policy below, runs the
-competitors only, never reading or porting their source. `--filter` takes
-a regex over corpus/subject/partition names; omit `--out` to skip writing
-JSON; `--compare BEFORE AFTER` prints a before/after comparison of two
-results files. The committed run lives at
-`packages/bench/results/results.json` (`--budget-ms 250`). The interpreter
-is the reference semantics, so ratios are informational, not a
-compatibility claim. [`packages/bench/README.md`](packages/bench/README.md)
-covers corpus provenance and licensing, methodology, and the recorded
-exclusions.
+`scripts/bench.py` times every jse tier (the interpreter, the compiler's
+flag validator and evaluator, and the standalone artifact) against two
+competitors (fastjsonschema, jsonschema) over seven corpora in
+`packages/bench`: three small hand-authored schemas, the official OpenAPI
+3.1 schema against a real document, a generated API-payload corpus, and
+two 2000-record corpora. Every jse tier is timed against every corpus,
+`jse standalone` against `oas-document` included, since its `$dynamicRef`
+sites resolve at plan time and leave no interpreted unit. Two subjects
+measure the record-producing tier against the verdict-only tiers:
+`jse interpreter list` and `jse compiled evaluator (list)`, both timing
+`output="list"`. The bench is report-only (it enforces no performance
+threshold) and, per the IP policy below, runs the competitors only, never
+reading or porting their source. `--filter` takes a regex over
+corpus/subject/partition names; omit `--out` to skip writing JSON;
+`--compare BEFORE AFTER` prints a before/after comparison of two results
+files. The committed run lives at `packages/bench/results/results.json`
+(`--budget-ms 250`). The interpreter is the reference semantics, so ratios
+are informational, not a compatibility claim.
+[`packages/bench/README.md`](packages/bench/README.md) covers corpus
+provenance and licensing, methodology, and the recorded exclusions.
 
 ## IP policy
 

{json_schema_engine-0.0.2 → json_schema_engine-0.0.3}/README.md

@@ -12,20 +12,16 @@ relevance model.
 
 Produced by Henry Andrews via Claude Code.
 
-**Status: `0.0.2` is the first functional release.**
+**Status: `0.0.3` is fully compliant except for draft-04 support.**
+
+See [CHANGELOG.md](CHANGELOG.md) for the current release's contents.
+[DESIGN.md](DESIGN.md) is the design contract and carries the milestone
+status.
 
 All `0.0.x` releases will have AI-written documentation.  Version
 `0.1.0` will indicate that the documentation has been audited and revised
 by a human.
 
-As of `0.0.2`, this package carries the
-interpreter core for 2020-12, 2019-09, draft-07, and draft-06 with every
-standard output format, the compiler tier (a flag validator and standalone
-modules, M6–M7), and the `json_schema_engine.formats` package — green on
-every official test-suite file for those drafts through both tiers, on the
-official output-tests, and on Bowtie. [DESIGN.md](DESIGN.md) is the design
-contract and carries the milestone status.
-
 The regular-expression translator lives in its own package,
 [`ecma-regex`](packages/ecma-regex/README.md) (`0.1.0`): ECMA-262 patterns
 for Python, with JavaScript semantics, no dependency on this engine.
@@ -66,12 +62,14 @@ one. Each keeps its own semantics, so a draft-07 `$ref` ignores its
 siblings while a 2019-09 one does not.
 
 Every standard output format is available by name: `flag` (the default),
-`basic`, `detailed`, and `verbose` from the IETF draft-03 output spec, and
-`list` and `hierarchical` from the machines-oriented proposal. Annotations
-are a separate control (`annotations=True`, or an `AnnotationSelection`),
-`verbose=True` asks `list`/`hierarchical` for the verbose level with
-irrelevant records marked as dropped, and `trace=True` adds the application
-tree with error indexes into `result.errors`.
+`basic`, `detailed`, and `verbose` from the
+[IETF working group draft-03](https://www.ietf.org/archive/id/draft-ietf-jsonschema-json-schema-03.html)
+output sections, and `list` and `hierarchical` from the
+[machines-oriented proposal](https://github.com/json-schema-org/json-schema-spec/blob/main/specs/output/jsonschema-validation-output-machines.md).
+Annotations are a separate control (`annotations=True`, or an
+`AnnotationSelection`), `verbose=True` asks `list`/`hierarchical` for the
+verbose level with irrelevant records marked as dropped, and `trace=True`
+adds the application tree with error indexes into `result.errors`.
 
 ```python
 result = engine.evaluate(uri, {"name": 3}, output="hierarchical")
@@ -102,9 +100,9 @@ attach a `source` location to every error and annotation, and
 ## Compile
 
 The compiler tier turns a registered schema into a Python function. It is
-not a second implementation: any subschema it cannot emit (a `$dynamicRef`,
-an `unevaluated*` whose coverage is only known at runtime, an in-place
-cycle) calls back into the interpreter, so a compiled validator is exactly
+not a second implementation: any subschema it cannot emit (a `$dynamicRef`
+whose target differs by path, an in-place cycle) calls back into the
+interpreter, so a compiled validator is exactly
 as correct as `Engine.evaluate` and never less complete. Tier choice is a
 performance decision, not a semantic one.
 
@@ -127,9 +125,25 @@ only the standard library and this package's pure helpers; it refuses,
 with `StandaloneUnsupportedError`, a schema that would need the
 interpreter at evaluation time. Compiled code assumes plain data as
 `json.loads` produces it (`dict`, `list`, `str`, `int`, `float`, `bool`,
-`None`); subclasses of those types belong to the interpreter. Errors,
-annotations, and the output formats are interpreter features today;
-compiled output beyond the verdict is a later milestone.
+`None`); subclasses of those types belong to the interpreter.
+
+`compile_evaluator` compiles a schema into an evaluator serving every
+output format the interpreter does — errors, annotations, dropped
+records, and the application trace, not only the verdict. The annotation
+selection is fixed at compile time; every other control (`output`,
+`error_params`, `verbose`, `trace`, `positions`) is chosen per call, same
+as `Engine.evaluate`.
+
+```python
+from json_schema_engine.compiler import compile_evaluator
+
+evaluator = compile_evaluator(engine, uri, annotations=True)
+compiled_result = evaluator.evaluate({}, output="list", error_params=True)
+interpreted_result = engine.evaluate(
+    uri, {}, output="list", error_params=True, annotations=True
+)
+assert compiled_result.errors == interpreted_result.errors
+```
 
 ## Formats
 
@@ -231,10 +245,6 @@ large arrays of distinct values do not incur quadratic cost, while genuine
 duplicates — including numbers equal across `int`/`float` and objects that
 differ only in member order — are still reported.
 
-**No prototype hazard.** Python dicts have no prototype chain, so there is
-nothing for a hostile property name to pollute: `__proto__`, `constructor`,
-and similar reserved-looking names evaluate as ordinary properties.
-
 ## Development
 
 ```sh
@@ -263,21 +273,26 @@ uv run python scripts/bowtie_check.py
 uv run python scripts/bench.py --budget-ms 250 --filter user
 ```
 
-`scripts/bench.py` times the compiler tier's flag and standalone artifacts
-against the interpreter and two competitors (fastjsonschema, jsonschema)
-over seven corpora in `packages/bench`: three small hand-authored schemas,
-the official OpenAPI 3.1 schema against a real document, a generated
-API-payload corpus, and two 2000-record corpora. It is report-only (it
-enforces no performance threshold) and, per the IP policy below, runs the
-competitors only, never reading or porting their source. `--filter` takes
-a regex over corpus/subject/partition names; omit `--out` to skip writing
-JSON; `--compare BEFORE AFTER` prints a before/after comparison of two
-results files. The committed run lives at
-`packages/bench/results/results.json` (`--budget-ms 250`). The interpreter
-is the reference semantics, so ratios are informational, not a
-compatibility claim. [`packages/bench/README.md`](packages/bench/README.md)
-covers corpus provenance and licensing, methodology, and the recorded
-exclusions.
+`scripts/bench.py` times every jse tier (the interpreter, the compiler's
+flag validator and evaluator, and the standalone artifact) against two
+competitors (fastjsonschema, jsonschema) over seven corpora in
+`packages/bench`: three small hand-authored schemas, the official OpenAPI
+3.1 schema against a real document, a generated API-payload corpus, and
+two 2000-record corpora. Every jse tier is timed against every corpus,
+`jse standalone` against `oas-document` included, since its `$dynamicRef`
+sites resolve at plan time and leave no interpreted unit. Two subjects
+measure the record-producing tier against the verdict-only tiers:
+`jse interpreter list` and `jse compiled evaluator (list)`, both timing
+`output="list"`. The bench is report-only (it enforces no performance
+threshold) and, per the IP policy below, runs the competitors only, never
+reading or porting their source. `--filter` takes a regex over
+corpus/subject/partition names; omit `--out` to skip writing JSON;
+`--compare BEFORE AFTER` prints a before/after comparison of two results
+files. The committed run lives at `packages/bench/results/results.json`
+(`--budget-ms 250`). The interpreter is the reference semantics, so ratios
+are informational, not a compatibility claim.
+[`packages/bench/README.md`](packages/bench/README.md) covers corpus
+provenance and licensing, methodology, and the recorded exclusions.
 
 ## IP policy
 

{json_schema_engine-0.0.2 → json_schema_engine-0.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "json-schema-engine"
-version = "0.0.2"
+version = "0.0.3"
 description = "A spec-complete, annotation-first JSON Schema engine for Python: interpreter, compiler, formats, every standard output format."
 readme = "README.md"
 requires-python = ">=3.12"

json_schema_engine-0.0.3/src/json_schema_engine/compiler/__init__.py

@@ -0,0 +1,250 @@
+# The compiler tier's public surface (DESIGN.md D1, D9, D10; M6): compile a
+# registered schema into a flag validator, or emit it as a standalone
+# module. The interpreter is the reference semantics; any subschema the
+# compiler cannot emit trampolines back into it, so an artifact is exactly
+# as correct as `Engine.evaluate` and never less complete — tier choice is
+# a performance decision, not a semantic one.
+#
+# An artifact binds a snapshot of the schema and dialect registries taken
+# at compile time: compile after registration is complete.
+#
+# Dependency direction: imports the planner, serializer, runtime, and
+# instantiation modules, plus core's engine façade. `json_schema_engine.core`
+# never imports this package (P5).
+
+import ast
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from json_schema_engine.compiler import emit as e
+from json_schema_engine.compiler.errors import (
+    FormatTableError,
+    StandaloneUnsupportedError,
+)
+from json_schema_engine.compiler.plan import (
+    CompilationExplanation,
+    CompilationPlan,
+    DynamicResolution,
+    FallbackCause,
+    PlannedApplication,
+    PlannedUnit,
+    ResolvedDynamicSite,
+    build_plan,
+    build_plan_over,
+    explain_compilation,
+)
+from json_schema_engine.compiler.runtime import make_namespace, make_runtime
+from json_schema_engine.compiler.runtime_compile import instantiate, instantiate_entry
+from json_schema_engine.compiler.serialize import Flags, assemble, serialize_plan
+from json_schema_engine.compiler.standalone import emit_standalone
+from json_schema_engine.core.channel_ops import cut_annotations
+from json_schema_engine.core.engine import Engine, assemble_evaluation
+from json_schema_engine.core.evaluator import EvalState
+from json_schema_engine.core.json_model import JsonValue
+from json_schema_engine.core.output import AnnotationsOption, make_record_predicate
+from json_schema_engine.core.result import OutputFormat, Result, resolve_output_demand
+
+__all__ = [
+    "CompilationExplanation",
+    "CompilationPlan",
+    "CompiledEvaluator",
+    "CompiledValidator",
+    "DynamicResolution",
+    "FallbackCause",
+    "FormatTableError",
+    "PlannedApplication",
+    "PlannedUnit",
+    "ResolvedDynamicSite",
+    "StandaloneUnsupportedError",
+    "build_plan",
+    "compile_evaluator",
+    "compile_validator",
+    "emit_standalone",
+    "explain_compilation",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledValidator:
+    """A compiled flag validator: `validate(instance) -> bool`, the plan it
+    was built from, the emitted module, and its source (for diagnostics
+    and goldens; `ast.unparse` of `module`)."""
+
+    validate: Callable[[JsonValue], bool]
+    plan: CompilationPlan
+    module: ast.Module
+    source: str
+
+
+def compile_validator(
+    engine: Engine,
+    schema_uri: str,
+    *,
+    max_depth: int | None = None,
+    conservative: bool = False,
+) -> CompiledValidator:
+    """Compile a registered root schema into a verdict-only validator.
+
+    `max_depth` defaults to the engine's; `conservative` turns the
+    emitter's optimizations off (no inlining, no set specialization) — the
+    differential fuzzer referees both configurations.
+    """
+    registry = engine.schemas.snapshot()
+    plan = build_plan_over(registry, schema_uri)
+    flags = Flags(inline=not conservative, specialize_sets=not conservative)
+    serialized = serialize_plan(plan, registry, flags)
+    prologue = [
+        e.assign(
+            name,
+            e.subscript(e.attr(e.load(e.RUNTIME), "re"), e.const(source)),
+        )
+        for name, source in serialized.regexes
+    ]
+    prologue.extend(
+        e.assign(
+            name,
+            e.subscript(e.attr(e.load(e.RUNTIME), "formats"), e.const(format_name)),
+        )
+        for name, format_name in serialized.formats
+    )
+    module = assemble(prologue, serialized)
+    budget = engine.max_depth if max_depth is None else max_depth
+    runtime = make_runtime(
+        registry,
+        engine.regex_cache,
+        plan.patterns,
+        budget,
+        formats=plan.formats,
+        format_table=engine.formats,
+        coverage_ids=plan.coverage_ids,
+    )
+    validate = instantiate(
+        module, make_namespace(runtime, [t.ref for t in plan.targets])
+    )
+    return CompiledValidator(validate, plan, module, ast.unparse(module))
+
+
+def _record_nothing(keyword_name: str, vocabulary_uri: str | None) -> bool:
+    return False
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledEvaluator:
+    """A compiled evaluator (M9): `evaluate(instance, *, output, error_params,
+    verbose, trace, positions) -> Result`, the same result `Engine.evaluate`
+    returns for that demand. The annotation selection is fixed at compile
+    time (ruled-out annotations are never recorded); every other output
+    control is chosen per evaluation. Records and the application trace
+    are written to a core `EvalState` the artifact shares with any
+    interpreted island, and rendered by the interpreter's own renderers.
+    """
+
+    evaluate: Callable[..., Result]
+    plan: CompilationPlan
+    module: ast.Module
+    source: str
+    annotations: AnnotationsOption
+
+
+def compile_evaluator(
+    engine: Engine,
+    schema_uri: str,
+    *,
+    annotations: AnnotationsOption = False,
+    max_depth: int | None = None,
+    conservative: bool = False,
+) -> CompiledEvaluator:
+    """Compile a registered root schema into an evaluator serving every
+    output format but the verdict-only `flag`.
+
+    Every consumer is tracked at runtime (a static coverage models only
+    the parent-success path, and an evaluator continues past a failed
+    sibling), nothing inlines, and every branch runs (§4 rule 7), so the
+    errors, annotations, dropped records, and trace equal the interpreter's.
+    """
+    registry = engine.schemas.snapshot()
+    plan = build_plan_over(registry, schema_uri, track_all=True)
+    flags = Flags(inline=False, specialize_sets=not conservative, mode="evaluator")
+    record = make_record_predicate(annotations)
+    serialized = serialize_plan(plan, registry, flags, record=record)
+    prologue = [
+        e.assign(
+            name,
+            e.subscript(e.attr(e.load(e.RUNTIME), "re"), e.const(source)),
+        )
+        for name, source in serialized.regexes
+    ]
+    prologue.extend(
+        e.assign(
+            name,
+            e.subscript(e.attr(e.load(e.RUNTIME), "formats"), e.const(format_name)),
+        )
+        for name, format_name in serialized.formats
+    )
+    prologue.extend(
+        e.assign(name, e.subscript(e.load(e.SITES), e.const(index)))
+        for index, (name, _) in enumerate(serialized.sites)
+    )
+    module = assemble(prologue, serialized)
+    budget = engine.max_depth if max_depth is None else max_depth
+    runtime = make_runtime(
+        registry,
+        engine.regex_cache,
+        plan.patterns,
+        budget,
+        formats=plan.formats,
+        format_table=engine.formats,
+        coverage_ids=plan.coverage_ids,
+    )
+    entry = instantiate_entry(
+        module,
+        make_namespace(
+            runtime,
+            [t.ref for t in plan.targets],
+            [site for _, site in serialized.sites],
+        ),
+        e.EVALUATE,
+    )
+    root_location = registry.root_ref(schema_uri).location
+    compile_regex = engine.regex_cache.compile
+    should_record = record if record is not None else _record_nothing
+
+    def evaluate(
+        instance: JsonValue,
+        *,
+        output: str | OutputFormat = OutputFormat.LIST,
+        error_params: bool = False,
+        verbose: bool | None = None,
+        trace: bool = False,
+        positions: bool = False,
+    ) -> Result:
+        demand = resolve_output_demand(
+            output=output,
+            annotations=annotations,
+            error_params=error_params,
+            verbose=verbose,
+            trace=trace,
+            positions=positions,
+        )
+        state = EvalState(
+            registry,
+            compile_regex,
+            should_record=should_record,
+            max_depth=budget,
+            tracing=demand.tracing,
+        )
+        valid = bool(entry(instance, state))
+        if not valid:
+            # The root application's records never merge (rule 3).
+            cut_annotations(state, 0)
+        return assemble_evaluation(
+            state,
+            valid,
+            demand,
+            annotations,
+            root_location,
+            trace,
+            locate=engine.locate if positions else None,
+        )
+
+    return CompiledEvaluator(evaluate, plan, module, ast.unparse(module), annotations)