# Performance

valgebra compiles a schema once into a Rust validator tree and crosses into Rust exactly once per validation call. This page records how that is measured, a reproducible baseline against other validators, the honest limits of the numbers, and the techniques behind them.

A speed claim is only as good as its methodology. Every number here states the harness, the dataset, the library versions, and the machine class. Re-run the harnesses on your own hardware before relying on a ratio: absolute times move with the CPU, and the comparison points do different amounts of work.

## What is measured

Two harnesses, one per side of the boundary:

- **Core micro-benchmarks** (`crates/valgebra-core/benches/core.rs`, criterion) time the pure-Rust schema transformations — the index remap behind validator composition and the recursive open/closed record transform — and the relations, a rule's answer (`subtype_*`, `is_empty_*`) beside the set representation's (`lower_*`). No Python is involved.
- **End-to-end benchmarks** (`benches/`, pytest-benchmark) time a single boundary-crossing validation call through the public API, over synthetic shapes that each stress one cost dimension.

Run them with:

```
# Core micro-benchmarks (Rust):
cargo bench --bench core

# End-to-end and comparison benchmarks (Python); install the bench group first,
# without the project, which the wheel below provides:
uv sync --locked --no-install-project --group bench
# To match the published figures, build the same PGO wheel the release ships
# (needs the llvm-tools rustup component) and install it; a plain build is slower.
# Every `uv run` from here on takes --no-sync: a sync reinstalls the project over
# the wheel, and the run then times a different build from the one installed.
uv run --no-sync --group bench maturin build --release --pgo --out dist
uv pip install --no-deps --reinstall dist/*.whl
uv run --no-sync --group bench pytest benches/bench_validate.py
uv run --no-sync --group bench pytest benches/bench_compare.py --benchmark-group-by=group
```

## Comparison is not apples-to-apples

The comparison runs the same shapes through three checkers that do **different** work. Read the ratios with that in mind:

- **valgebra** checks membership of the object already in hand: no copy, no coercion. `is_valid` returns a bool through the membership fast path.
- **jsonschema** (`Draft202012Validator.is_valid`) is also a pure check with no coercion — the closest semantic analog — but it is pure Python.
- **pydantic** (`TypeAdapter.validate_python`, strict mode) validates *and constructs* a value. Strict mode disables coercion, but it still builds and returns output, so it does strictly more work than a membership check. It is the relevant point of comparison because it is the Rust-cored validator most users reach for.

The record shape compares valgebra's closed record against a pydantic `TypedDict` and a jsonschema object with `additionalProperties: false`, so all three check the same set of named fields.

Two libraries check an object in hand against its annotation, as valgebra does, and the matrix leaves both out: **typeguard** and **beartype**. Neither reads every element by default. typeguard checks the first item of a collection unless its `collection_check_strategy` is `ALL_ITEMS`, and beartype checks one item drawn at random, so `[1] * 999 + ["x"]` passes as a `list[int]` on every call of the first and on most calls of the second. A ratio against a check that reads one element measures what sampling buys, not the same work; typeguard under `ALL_ITEMS` does the same work, in Python.

## Baseline matrix

Machine class: AMD Ryzen 7 PRO 7840U (Zen 4, 8c/16t, up to 5.1 GHz, a 2023-era mobile part) under WSL2 on Linux 6.18. Toolchain: rustc 1.100.0 (the build these numbers are measured on; the supported minimum is the lower `rust-version` in the manifest), CPython 3.15.2 built from source with `--enable-optimizations --with-lto`, `CC=clang` and `CFLAGS=-march=native -mtune=native`, and **the GIL enabled** (`sysconfig.get_config_var("Py_GIL_DISABLED")` is `0`; the free-threaded build of the same version takes 1.4 to 2.8 times as long to walk a container, so a figure measured on one is not comparable with the other). Every package version -- the two benchmark harnesses and the libraries compared against -- is whichever the bench group resolves. `uv.lock` owns them and `scripts/compare_gate.py` prints them beside the figures, so none is written here: a version copied into prose is stale the next time the lock moves, and a reader cannot tell a stale one from a current one.

`sysconfig.get_config_var("CONFIG_ARGS")` reports that build, and is how to check you are on it. The native tuning is the flag that matters when reproducing these numbers: a stock distribution interpreter is a different binary, and so is the one `uv sync` provisions for this repository, which is a python-build-standalone image rather than a source build. Point the bench environment at the interpreter you mean -- the sync rebuilds `.venv` on it --

```
uv sync --locked --no-install-project --group bench --python /path/to/that/python
uv run --no-sync --group bench maturin build --release --pgo --out dist
uv pip install --no-deps --reinstall dist/*.whl
uv run --no-sync --group bench python scripts/compare_gate.py
```

\-- because a figure measured against another binary is not comparable with a figure here.

The extension is the **PGO** release build — the profile-guided, fat-LTO wheel the release ships, which the `maturin build --release --pgo` step above builds.

pydantic's PyPI wheels are likewise PGO-built, so this is a release-to-release comparison.

**Read no figure taken from a debug build as either** -- `maturin develop` without `--release` installs one, it is indistinguishable from the release extension at the Python prompt, and a timing of it reads an order of magnitude slow. `scripts/compare_gate.py` refuses such a build outright, and so does `benches/` from its own `conftest.py`; a figure timed by hand has only the habit to protect it.

**Whether to add PGO is a question about your shapes**, not a setting to turn on. Build both, install each in turn, and time the shapes you run on it -- the sequence the `pgo compare` lane in `.github/workflows/ci.yml` runs:

```
uv sync --locked --no-install-project --group bench
uv run --no-sync --group bench maturin build --release --out plain
uv run --no-sync --group bench maturin build --release --pgo --out profiled
uv pip install --no-deps --reinstall plain/*.whl
uv run --no-sync --group bench python scripts/pgo_compare.py \
  --record plain.json --label plain
uv pip install --no-deps --reinstall profiled/*.whl
uv run --no-sync --group bench python scripts/pgo_compare.py \
  --record profiled.json --label pgo
uv run --no-sync --group bench python scripts/pgo_compare.py \
  --compare plain.json profiled.json
```

That script times every shape the competitive gate judges -- it reads them from `scripts/compare_gate.py` -- so the two tables speak of the same workloads. It refuses a reading from a debug build and refuses to compare two readings from different interpreters, because a ratio between builds cancels the machine and not the interpreter.

Measured that way on the box above, six readings of each build interleaved, the profile buys on six shapes, by the median of the six: the list nested twenty-five deep 36%, the JSON document 25%, the one-`int` call 19%, compilation 18%, the error report 5%, and the accepting walk over a fifty-field record 4%, between 3% and 5% across the six. The ten-thousand element `list[int]` reads 10% slower, between 5% and 13%. A single reading of one shape is not a verdict either way: the first reading after an install can part from the five after it by 12%.

The shape the profile costs is the one with the least left to arrange, and what moves it is where its code lands rather than what its code does. A list of one scalar kind is read by a loop of its own for that kind, a type test per element, and that loop counts within 0.9% with a profile and without one. On CPython 3.15 it takes 0.94 ns an element in the plain wheel and 1.04 in the profiled one. Two profiled wheels built from one source count it to the instruction and take 1.0 and 1.2 ns, so this figure follows where a build lands the loop, the effect [aligning code to 64 bytes](<#measured-and-not-taken>) reads on another list. The shapes that gain are the ones a call crosses several functions to answer: the boundary itself, a descent through twenty-five levels, a parse and then a walk.

**The reading the release matrix is decided on is taken where the release builds.** The `pgo compare` lane builds both wheels from one source, times every shape on each, and uploads the two readings, on both interpreters the bench jobs use -- a global lock changes what a per-element loop costs, and the shapes a profile serves best are the per-element ones:

```
gh workflow run CI -f pgo_compare=true
```

**The training workload is the lever**, not the flag: the profile is taken over `scripts/pgo_workload.py`, which `pyproject.toml`'s `pgo-command` names, and what that workload spends its time on is what the layout is arranged for. A change to it is measured on both sides of the comparison above, since a profile re-weighted toward one shape is a profile taken away from another.

**A loop the profile holds no counts for is laid out by chance.** A homogeneous list takes a loop of its own, so a workload reading only homogeneous lists holds no counts for the general scan every list of records and every nested list is read through, and whether that scan stays inside the recursive walk is the inliner's guess. A change to the list arm's code can turn it: untrained on the scan, the comparison gate's list nested twenty-five deep takes 64% longer in the PGO wheel, 405 ns against 245 on one box, while the instruction gate's plain workloads, which build without a profile, read 0.9%. So the workload reads a list of records and a list nested twenty-five deep, and trained on them that shape reads 0.101 of pydantic's time on CPython 3.15. The instruction gate holds the training too, counting the comparison gate's shapes on the PGO wheel built at a change and at its base (`perf_gate.py --profiled`): built with the nested list's training taken out, that shape reads 50.89% more instructions.

A record inside a list is laid out by the lists of records the workload reads, and weighted lightly, its reading moves with code beside it that it never runs: trained a quarter as often, on records of scalar fields alone, a list of two hundred records whose record holds a list reads 1.3% more instructions on the profiled wheel. So the workload reads its lists of records at the weight a document's records are read with, one of them of records holding a list.

A path's weight moves a path it does not touch. Trained at 2,000 rounds, a list of refined floats reads the list nested twenty-five deep 6% to 9% dearer in cycles at one count, the instructions on that list's path the same and laid out otherwise, on two builds of one tree. At 500 rounds that list reads between 1% cheaper and 4% dearer across two builds, the spread of a shape of that size, for 3% more instructions on the floats, and untrained the floats read 54% fewer instructions than through the rich comparison where trained they read 69%.

A parsed JSON array of records is read through a loop of its own (`record_array_matches`), and untrained it is laid out by chance too: two builds of one source read the comparison gate's document 10% apart in instructions, and a source path one character longer is enough to move it. Trained, every build reads one count, within 0.2%, and the document takes 12 to 14% less time than untrained on CPython 3.14.

The same holds for a reader the workload never enters: the lists a reader of their own settles -- a union of literals, one class, a union of scalars, a tuple of scalars, a named tuple of them -- sit beside the general scan, and untrained, the readers for literals and classes move the PGO wheel's walk of a nested list by 6% in instructions. The workload reads a list of each kind, which takes that to 3%.

And for a door the workload never calls. `x in v` reaches the check through a slot of its own, into which the build inlines a copy of it; untrained, that copy took a mispredicted branch on every call and read 13% slower, and the workload calls it at no cost to any shape the profiled gate counts. `load` parses into Python objects through a builder no other call takes, and it is left untrained, where it reads 49% slower than a build trained on it, on the comparison gate's document and through `validate_json` alike, which parses the same way. That is a trade the gate refuses: trained on a document of records, at every weight tried, the profile lays the general list scan out for long lists, and the list nested twenty-five deep, one element a level, reads 3.5 to 7% more instructions on the profiled wheel and 2.5% more time.

**What the matrix does with the reading.** `--pgo` ships on five targets, and that is a claim about those boxes rather than a default. Where the lane reads a gain on the shapes the release serves, the matrix keeps `pgo: true` and this page names the shapes it costs. Where it reads the record walk slower on both interpreters -- the shape most callers spend their time in -- `pgo: true` leaves the matrix and this page says so. Either way the decision is the reading's, and the reading is the lane's.

That is one microarchitecture and one interpreter, and the release lane builds on five targets none of which is this one, so it is a reason to measure your own build rather than a ranking. `scripts/compare_gate.py` against each wheel is how.

**Every wall-clock figure on this page, and in the changelog, is a release build on an idle machine, read over repeated runs -- a median of ten for a table, taken as two sets of five, and the comparison gate's minimum for a ratio, taken twice.** The two guards above hold the first of those and neither holds the other two: a timing taken while something else has the CPU reads slow, and one taken once reads whatever that run did. Either is enough to put a published figure out by a factor, so the discipline is written down rather than assumed.

How much PGO adds over a plain `--release` build is not a constant this page can state, and on some shapes it is not a gain at all. It is whatever the profile can still arrange that fat LTO did not, so it shrinks as the hot paths get shorter, and where the layout it picks suits one shape it can cost another.

The figures are measured on the wheel carrying valgebra's full feature set — the per-validator precompute (record-field lookups, literal-union dispatch) and native string patterns — which leaves these shapes unchanged: the features earn their keep elsewhere, not by regressing the core.

### Method

Each cell is the **median of ten independent runs** of the comparison benchmark, two sets of five, each run reporting pytest-benchmark's own median over its rounds. The `+/-` is the half-range across the ten runs, not a standard deviation: it states the observed spread rather than modeling one. With the release wheel installed as above:

```
uv run --no-sync --group bench pytest benches/bench_compare.py --benchmark-json=run.json
```

The **ratios** have their own gate, which measures only valgebra against pydantic and takes the minimum over many repeats rather than a median:

```
uv run --no-sync --group bench python scripts/compare_gate.py
```

That script owns the per-shape ratio **ceilings** (`scripts/perf_compare.json`) -- what the project claims it stays under rather than a recorded measurement -- and the table below is the absolute record. The two estimators can part by a quarter of a multiplier — a minimum sits below a median by however much the run was disturbed, and the 3.15 results below read both — so read a cell here against the same cell, not against the gate's output.

**One command re-reads every figure on this page and on the [JSON page](<https://ppigazzini.github.io/valgebra/guides/json/index.md#performance>)**, on the checkout as it stands or on the commit `--rev` names:

```
uv run --no-sync python scripts/page_figures.py \
  --python-315 /path/to/that/python --python-314 /path/to/its/3.14
```

It needs `uv`, the `llvm-tools` component the PGO build needs, and the five interpreters the tables name: the two passed, CPython 3.15 and 3.14 built from source alike, and CPython 3.12 and the free-threaded 3.14 and 3.15 as `uv` installs them, unless `--python-312`, `--python-314t` and `--python-315t` name others. It builds everything it times under `target/page-figures/`, every wheel from one directory, takes the readings one at a time, and prints each figure under the name of the section that states it. `--stage` runs one of those three steps alone, and `--help` says what each holds. `MEASURE` in the script holds the repeats this section states, and `tests/test_page_figures.py` holds the page to it.

On the machine above the build takes about ten minutes and the readings about seven, and the readings are a wall clock: run them on an idle machine, with nothing beside them. The script edits no page. A figure is copied in by hand once read, because a run something disturbed reads slow, and only a reader can tell that from a figure that moved. Of the figures under [How the speed is made](<#how-the-speed-is-made>), it re-reads the three that state a cost of this tree: the reference pool's pair, the fifty refined fields' build and the report on a deep value. A figure stating a technique's before and after is a pair built where the technique landed, and the changelog's figures are each fix's own pair, on the build its entry names; it re-reads neither.

### The cheapest door, and where the floor is

`x in v` is `v.is_valid(x)` through the container protocol, and it is the cheaper call: **12 ns against 18 ns** for a scalar on the machine above, the best of fifteen `timeit` repeats of a million calls, because the interpreter reaches a container slot directly and a method by its call protocol. Neither number is the check. `Validator(anything).is_valid(1)` -- the schema that answers `True` without looking -- costs 18 ns, nearly as much, since a validator of one scalar kind is its type test and enters no walk, so what is left is the boundary a Python call crosses. For reference on the same run, `isinstance(1, int)` is 13 ns and a call to an empty one-argument Python function is 17 ns.

Read that as the floor it is: a per-call check cannot be much cheaper than a Python call, and the way to spend less is to make fewer calls -- validate the list, not each element -- rather than to look for a faster scalar.

### Results

End-to-end validation of a value that passes (lower is better):

| Shape | valgebra | pydantic (strict) | jsonschema |
| --- | --- | --- | --- |
| `list[int]`, 10,000 elements | 10.4 +/- 0.18 us | 87.2 +/- 1.2 us | 25,410 +/- 650 us |
| Closed record, 50 int fields | 0.481 +/- 0.015 us | 2.02 +/- 0.12 us | 133 +/- 3.1 us |
| Nested `list[...]`, depth 25 | 0.183 +/- 0.037 us | 2.04 +/- 0.045 us | 75.6 +/- 2.4 us |

valgebra relative to pydantic on this machine, under the CPython 3.15 the matrix above names, as the medians above divide: **11.2x** faster on deep nesting, **8.4x** on the large flat array, **4.2x** on the wide record. The comparison gate's minimums read the same three at 10.2x, 8.4x and 4.6x (the 3.15 column below). It is consistently far ahead of pure-Python jsonschema — 2,438x on the array, 413x on the nesting and 276x on the record. The nesting's half-range is its slowest run of the ten, which read 0.250 us; the other nine read 0.177 to 0.193.

pydantic does strictly more work on the record (it constructs output), so read that shape as a margin over a heavier operation, not a like-for-like loss for pydantic.

### One of those margins moves with the interpreter

A ratio cancels the machine — a slower box slows both sides — and it does not cancel the interpreter. Running the comparison gate on one box against five of them -- CPython 3.12.16 and the free-threaded 3.14.10 and 3.15.2 as `uv` installs them, beside the 3.15.2 build named above and a 3.14.10 built the same way -- as the fraction of pydantic's time each shape takes, the median over twelve runs on 3.12 and 3.14, eighteen on 3.15 and seven on each free-threaded build:

| Shape | CPython 3.12 | CPython 3.14 | CPython 3.15 | 3.14 free-threaded | 3.15 free-threaded |
| --- | --- | --- | --- | --- | --- |
| `list[int]`, 10,000 elements | 0.159 | 0.107 | 0.119 | 0.143 | 0.135 |
| Closed record, 50 int fields | 0.224 | 0.212 | 0.219 | 0.234 | 0.234 |
| Nested `list[...]`, depth 25 | 0.105 | 0.090 | 0.098 | 0.229 | 0.237 |
| One `int` | 0.160 | 0.155 | 0.171 | 0.163 | 0.175 |

The **element** is what moves, not the check. A list hands out each of its items as an owned reference — a count written on the object when the handle is made and again when it drops — and the free-threaded build writes each count through a call into the interpreter. A schema nested twenty-five deep is twenty-five containers of one element, so it is almost nothing but that cost, and it takes 2.6 to 2.8 times as long there as under a global lock. A flat array of ten thousand is read through a snapshot of the list under 3.12 and the free-threaded builds, which pays the counts in two loops inside the interpreter and none in the walk; CPython 3.14 and 3.15 with their global lock make the counts cheap enough that the walk reads the list in place (`snapshot_pays` in `crates/valgebra-py/src/check/walk/sequence.rs`). The array's cell parts those two by where each build lands the loop: it reads 0.97 ns an element in the 3.14 wheel and 1.04 in the 3.15 one, and [two builds of one source](<#baseline-matrix>) read 1.0 and 1.2. The margin carries across all five.

That is why the ceiling file holds a second set for the free-threaded build: what the project claims of that build is what that build can hold.

### Threads on the free-threaded build

A `Validator` is immutable, so every thread can share one. What decides how the free-threaded build scales is what the **values** the threads check share, and the walk's reading of a container says how. A list, a dict and a set are read under that container's own lock (`with_critical_section` in `crates/valgebra-py/src/check/walk/`), and a list hands out each element as an owned reference, whose count the free-threaded build writes on the element itself:

| What the threads check | How it scales |
| --- | --- |
| one value, shared | not with the threads: they take turns on the lock of every list, dict and set they share |
| a `copy.deepcopy` each | with the threads, less the more elements the copies share: `deepcopy` returns an immutable element such as an `int` as it is, so every thread reading it out of its list writes that element's count |
| a value each, of its own objects | with the threads |
| a JSON document each, parsed from one shared string | with the threads: the parser takes a string cache from a pool behind one lock, and holds the lock only to take it and put it back |

So a server checking each request's own payload scales with its threads, and threads checking one shared structure do not. The [installation page](<https://ppigazzini.github.io/valgebra/get-started/installation/index.md#free-threaded-cpython>) says what to do about the second.

### The closest races

The table above holds four of the shapes the competitive gate judges; `scripts/perf_compare.json` names every one with the ceiling the project claims for it, and `scripts/compare_gate.py` prints each beside its ceiling. A record of only the wide margins would be a selection, so here are the two closest, as the fraction of pydantic's time each takes, on the PGO CPython 3.15 build above:

| Shape | ratio | spread across runs |
| --- | --- | --- |
| JSON document, 200 records parsed and checked | 0.52 | 0.044 over eighteen runs |
| Error report, 50-field record with one wrong field | 0.46 | 0.024 over eighteen runs |

The JSON document is a single pass over bytes for both libraries, which is why valgebra takes about half of pydantic's time here rather than a fraction: neither is spending its time in the check. A document's free-form sections are `dict[str, V]`, and covering their keys is read two ways -- in place for a narrow object, through a table of last values for a wide one (`docs/dev/walk.md`).

Across the eighteen runs the JSON document spreads 0.044, the widest of the seven; beside it the nesting 0.037, seventeen of its runs within 0.006 and one reading 0.132, the error report 0.024, the record 0.020, the scalar, which sits near timer resolution, 0.016, the array 0.008 and the build 0.0004. The error report is the only shape timing a path that raises and formats a Python exception, so a Python exception's cost is inside the number. It is excluded from the gate's drift ratchet, and `scripts/perf_compare.json` gives the reason rather than leaving an absent entry to mean it: a spread on another build wider than any regression worth catching. The ratchet holds the JSON document and the other five shapes, armed from a window of the bench lane's readings rather than one run, since the lane reads one tree on several classes of machine further apart than a tolerance (`docs/dev/tooling-ci.md` has the window); the error report is judged against its ceiling alone.

A failing validation walks the value **twice** here -- once to decide, once to say which field -- where pydantic-core walks it once and collects as it goes. That is a deliberate trade for the passing path, which is the common one and which walks once. The second walk does not repeat the first: it resumes where the deciding walk stopped, since a field that matched has no violation to report (`docs/dev/walk.md`). Resuming rather than restarting is worth 36.8% of that walk on the instruction gate, which `scripts/perf_gate.py --binding-explain` measures. What the report pays beyond the deciding walk is one walk of the fields *after* the failure, and the exception.

The scalar shape is absent from the table because it sits near timer resolution, and most of it is the call rather than the check, as the floor above shows: on CPython 3.15 the competitive gate measures it at a 32.0 ns median over eighteen runs, between 31.4 and 33.8 ns, around 5.9x. That gate measures it; this record does not.

Core micro-benchmarks (criterion, release+LTO, indicative single run):

| Operation | Corpus | Median |
| --- | --- | --- |
| `reindexed` | 64-field pool-indexed record | \~1.2 us |
| `with_records_open` | record spine, depth 32 | \~4.2 us |

## Honest limits

- The numbers are a single machine class. They establish relative behavior, not a universal ranking. Shared CI runners are too noisy for a tight wall-clock budget, so the merge gate measures a deterministic instruction count instead.
- The margins against pydantic come with the caveat that the two tools do different work: pydantic constructs output, valgebra only checks membership. The ratios answer "how fast is each tool's validation step," not "how much faster is membership than construction." The record's margin is the narrowest on every interpreter measured, and which of the other two is the widest moves with the interpreter: nesting leads on CPython 3.12, 3.14 and 3.15, and the array on the free-threaded builds.
- **The ratios are not the whole argument for using valgebra.** They are real, and they are also a regression gate. But the reasons to reach for a membership check over a parser are additionally semantic — an already-held object is re-examined rather than passed through, a value stays checkable after it is mutated, and schemas can be compared as sets — and every one of those would hold even at a ratio of 1.0. `tests/test_pydantic_boundary.py` pins them as verdicts, with no timer involved.
- The comparison measures different operations (check vs check-and-construct vs pure-Python check). It answers "how fast is the validation step for each tool," not "are these tools interchangeable" — they are not. See the README for what valgebra is and is not for.
- These figures are for the object path — validating a value already in hand. The JSON input path is measured separately, on the same machine class, in the [JSON page](<https://ppigazzini.github.io/valgebra/guides/json/index.md>).

## How the speed is made

Every technique below changes how an answer is reached and never the answer. Where a cheap reading stands beside the general one, a test asks both and holds them to one verdict, so a rule changed in one and not the other fails. Where only the cost moves, no test can tell the readings apart, and a shape of the instruction gate holds the cost instead: `scripts/perf_gate.py --against <rev>` measures it against a base, and the flag a figure below names is the shape that reproduces it. A percentage compares a technique with the reading it stands beside or replaces; where that reading stays in the tree, it is the fallback, and where a test keeps it, the test holds the two to one answer.

Each entry names the code that owns it. The developer pages in the repository carry the arguments in full: the walk (`docs/dev/walk.md`), the frontend (`docs/dev/frontend.md`), the relations (`docs/dev/decision.md`), the error model (`docs/dev/errors.md`) and the schema representation (`docs/dev/schema-ir.md`).

### Crossing into Rust

- **One crossing per call.** `is_valid`, `validate` and `is_valid_json` enter the extension once and walk the whole value in Rust. Python runs during a walk only where the schema or the value brings code of its own: a predicate, a class whose metaclass computes `isinstance`, a property read as a field, a value's own `__eq__`. What the crossing itself costs is the floor [the cheapest door](<#the-cheapest-door-and-where-the-floor-is>) measures.
- **No reference pool.** PyO3 keeps a pool of reference-count decrements deferred while a thread is detached, and once any of its lazy initializers has detached and attached again -- the first interned name does -- every call into the extension locks that pool's mutex to ask it for them: forty instructions and eight branches on `Validator(int).is_valid(1)`. The binding never detaches, so the pool is always empty, and `.cargo/config.toml` compiles it out; `tests/test_build_flags.py` holds the flags there. The instruction gate's boundary shape calls the walk without crossing PyO3's call machinery, so the comparison gate's `scalar` is the instrument that reads it: 32.1 ns with the pool gone against 33.9 with it, on CPython 3.15 and the machine named above.
- **A failure is raised in one step.** `into_pyerr` in `crates/valgebra-py/src/errors.rs` builds the `ValidationError` instance and hands it to PyO3 as the error's value, so the raise is one `PyErr_SetObject`. A lazily built error is normalized by releasing the interpreter lock and taking it back, which lets another thread run in the middle of a raise and costs a failing `validate` of a fifty-field record 5.4% more instructions. The exception being handled is chained as `__context__` either way, and a test holds that on every interpreter the suite runs.
- **Every fixed name is one the interpreter already holds.** An attribute, key or method name crosses as an interned string (`intern!`), which carries its hash; a name handed over as Rust text is decoded into a new string and hashed on every lookup. An attribute that may be absent is asked for with `getattr_opt`, which answers without building an exception wherever the interpreter offers a lookup that does (`PyObject_GetOptionalAttr`, from 3.13).
- **Internal maps hash with FxHash.** A validator's own maps are keyed by its field names and by object identities, so they use `rustc-hash` rather than the standard hasher and its per-map random seed. The one table a document's own keys fill -- the last entry of each undeclared key in a wide parsed object -- hashes with `ahash` instead, keyed per process, because an unseeded hash lets a document carry keys computed to collide; it is also filled once a key, the position a repeat displaces read off the insert, which makes the wide object 9% to 14% cheaper than an FxHash table.

### Building a validator

Compiling happens once per schema, so these are startup costs. They matter to a program that builds validators per request, and to no validation call.

- **A type is dispatched before any `typing` introspection**, and an exact `bool`, `int`, `float`, `str` or `bytes` constant, or a `Validator`, is read before the frontend's dispatch (`builtin_constant` in `crates/valgebra-py/src/build.rs`). A `Literal` of two thousand string codes compiles in about three million instructions; read through the whole dispatch one constant at a time, it costs four times that. The pool indexes its constants by type and value or by address (`Pool::intern_keyed`), so interning one is a lookup rather than a scan.
- **The `typing` forms are resolved once per interpreter** (`forms` in `build.rs`), and `dataclasses` is imported on the first dataclass a program compiles (`DATACLASS_READING` in `build/classes.rs`). Held among the forms, its import would leave tracked objects behind that lengthen every later garbage-collection pass, and a build that compiles no dataclass would read 6.45% dearer on `--binding-build`. The table of loaded modules is held too (`loaded_modules` in `build.rs`): a `TypedDict` from CPython 3.15, and one `typing_extensions` builds on any release, asks it once per class for the sentinel that says no `extra_items` were given, and importing `sys` to ask is 12% of compiling a three-field one.
- **An alias of a builtin container, and a union written with `|`, are read off the object** (`builtin_alias` in `crates/valgebra-py/src/build.rs`). `typing.get_origin` and `typing.get_args` read the same two attributes for them through three Python calls, after an attribute no such form carries is asked and answered by an `AttributeError` raised, formatted and cleared: compiling `int | str | list[int] | dict[str, int] | None` reads 68% fewer instructions on the profiled CPython 3.15 wheel, and a test holds the two readings to one answer.
- **A class is asked whether it is a dataclass by its attribute** (`is_dataclass` in `build/classes.rs`). `dataclasses.is_dataclass` is `hasattr(cls, "__dataclass_fields__")` once its argument is a class, on every interpreter the matrix runs, so the attribute is asked in its place: a class node pays no Python call for it, and a schema naming classes and no dataclass never imports the module (`--binding-object`, `--binding-protocol`).
- **A class's annotations are read as written** wherever evaluating them would hand each one back unchanged (`annotations_as_written` in `build/classes.rs`). `typing.get_type_hints` exists to evaluate forward references, and on a class with none it still copies every base's namespace and walks every annotation in Python. The reading takes the call's steps and declines every case the call would rebuild -- a string, a `ForwardRef`, a nesting deeper than `MAX_ANNOTATION_DEPTH` -- so an answer or an error a caller sees is the call's. A Rust interpreter test compares the two over a corpus of classes on every supported interpreter. A static builtin base -- `object`, `tuple` under a `NamedTuple`, `dict` under a `TypedDict` -- holds no annotations and is not asked for them (`annotates_nothing`): from 3.14 the asking is a Python call that raises and drops an error for each, and skipping it makes a `NamedTuple` compile in 45% fewer instructions on CPython 3.14 and 3.15, a five-field `TypedDict` in 30% fewer, and a dataclass in 16% fewer. A class of the program's own is read through `type`'s own `__annotations__` descriptor, which `annotationlib.get_annotations` asks first and whose `dict` it copies (`own_annotations`); the call, two Python functions, answers only what the descriptor leaves to it. From 3.14 that makes a three-field `TypedDict` compile in 19% fewer instructions, a `NamedTuple` in 14% and a dataclass in 7% (`--binding-protocol`, `--binding-object`).
- **A dataclass's fields are read as `dataclasses.fields` reads them** (`fields_as_declared`), and an order bound of exactly `int`, `float` or `bool` is placed without asking the `numbers.Number` ABC, whose `__instancecheck__` is a Python function (`is_a_number` in `build/refine.rs`). A subclass is still asked, because the ABC reads a value's `__class__`, which a subclass may answer with code of its own.
- **A refinement marker is read by its type, once.** A marker carries one or two of ten optional attributes and not the rest, and below 3.13 asking for one it does not have is answered by raising. So the frontend asks the marker's *type* which names it carries and remembers the answer, up to `MAX_MARKER_TYPES` types, which costs no exceptions on any interpreter: fifty `Annotated[int, Ge(0)]` fields compile in about 13 us on CPython 3.15, 13 on 3.14 and 13 on 3.12, on the machine named above.
- **A `TypedDict` field's qualifiers are read once.** The reader that says whether a key is required walks the `Required`, `NotRequired` and `ReadOnly` around a field's hint, below the first that answers so that two which disagree are refused, and hands back the type below them, which the field is built from (`qualified_required` in `build/classes.rs`). The builder reaches a qualifier only after asking the hint every form before it, so it is spared that walk: fifty refined fields, five of them `NotRequired`, compile in 12% fewer instructions than built from the hint as written (`--binding-annotated`).
- **A protocol reads its classes' namespaces once**, and a member annotated with a class `type` made is neither `ClassVar` nor `Final` without calling `typing.get_origin`, a Python function (`protocol_members` in `build/classes.rs`; `--binding-protocol`).
- **A class's missing attribute raises nothing on CPython 3.12.** A build asks a class for attributes it nearly always lacks -- the `__origin__` of a `TypedDict` field's hint, the `__unpacked__` of a tuple's type arguments, `_is_protocol` -- and below 3.13 PyO3 answers a miss with an `AttributeError` built, its message formatted for a class, and cleared. On 3.12 a class is asked through the builtin `getattr` with a default instead (`optional_attribute` in `build/classes.rs`), whose lookup answers without the error: a fifty-field `TypedDict` of `int` compiles in 59% fewer instructions there, and the binding gate's protocol build in 8.61% fewer (`--binding-protocol`). From 3.13 PyO3 asks without the error, and 3.11 builds it on either road.
- **A validator is accepted on one walk of each tree.** `Schema::measure` in `crates/valgebra-core/src/ir.rs` reads the nesting depth, the node count and the self-reference marker in one level-by-level walk against two buffers, and descends no native stack.
- **What the walk needs is built once per validator.** `ValidatorIndex` in `crates/valgebra-py/src/check/index.rs` holds each record's name-to-position plan, its keys and attribute names interned, each literal union's tables and each compiled pattern. It is keyed by the address of the schema's own buffers, which are stable for the life of the immutable schema, so a copied validator never inherits another's index; and a node the build traversal does not reach falls back to reading its own text, so no verdict depends on the index being complete. A report does -- a record with no plan is read by its entries, and which branch of a union of records is explained follows that reading -- so the traversal reaches every node a record can sit under. A dataclass instance's attributes are read through the interned names, which `--binding-object-walk` counts.

### Walking a Python value

- **The leaf decision is a test where the answer is.** `admit` in `crates/valgebra-py/src/check/walk/scalar.rs` is inlined, and recording a violation is a `#[cold]` function of its own, so the accepting path is one comparison and the allocating path sits apart from it.
- **A scalar is its type test.** A union's scalar branch, a mapping clause's key and value, a record's scalar field and the elements of a sequence of a union of scalars ask the type test directly (`scalar_member`, and `field_holds` in `check/walk/record.rs`), reading the depth level and the fatal-signal flag as the general walk does, so each refuses exactly where the walk refuses. A thousand-element `list[int | None]` costs 87% fewer instructions that way. A mapping whose one clause is two scalars reads the level and the flag once for the dict, and its entries as two type tests each (`scalar_map_matches`): a hundred-entry `dict[str, int]` costs a third fewer instructions that way on the profiled wheels, and the binding gate's sixty-four entries 43% fewer (`--binding-mapping`). A mapping of several such clauses asks each clause's two tests in turn (`scalar_clauses_match`): a hundred-entry `{str: int, int: bool}` costs 41% to 42% fewer instructions than the scan on the profiled 3.12 and 3.14 wheels. A Rust test holds the direct reading to the walk's verdict for every scalar schema against every kind of value.
- **A literal's check stays out of the walk's every node.** A relation walks a literal's constant, so a profile reads `check_literal` as hot, and inlined into `member` its explaining half puts 300 instructions and 48 bytes of frame in every node of every walk: a list nested twenty-five deep reads 1.2% more instructions and 4.2% more cycles. It is out of line, so the profile a relation trains cannot bring it back.
- **An instance of the class itself is read off its type pointer.** `type(obj) is C` answers `isinstance(obj, C)` before `C.__instancecheck__` is asked, which is the test CPython's `PyObject_IsInstance` makes first (`is_exactly_a` in `check/walk.rs`). PyPy implements `isinstance` otherwise, and there the call answers.
- **A literal's own constant is answered by its address.** A literal written in a program's source is usually the very object it validates: an interned string, a cached small integer. An exact `str`, `int`, `bool`, `bytes` or `None` that *is* the pooled constant equals it, so `is_the_constant` answers without a comparison. A `float` is excluded, since a NaN is not equal to itself. Either way the value is compared where the walk holds it, writing no reference count, and only a parsed JSON value is built into an object (`check_literal`): a check against one `Literal` costs 2.4% fewer instructions on CPython 3.14 and 4.1% fewer on 3.14t, where PyO3 reaches a reference count through a call into the interpreter.
- **A validator of one scalar kind is its type test.** A schema that is one kind at the root is answered before the walk's state and context are built (`root_scalar` in `check/walk/scalar.rs`): a walk that has not begun holds no signal and every level, so nothing around the test can refuse. `is_valid` on an `int` reads 22% fewer instructions on the profiled CPython 3.15 wheel, the interpreter's own call included, `validate` of a value that belongs takes the same road, and every other schema pays a load and a comparison.
- **A refinement borrows its operand and renders nothing on a pass.** The bound is read out of the pool as a borrow for the whole check, and the value from the walk, so a passing check writes no reference count; a scalar base that admits the value is its type test rather than a walk (`check_refine`; `--binding-refined`). A violation's message, which needs the bound's `repr`, is built only at the site that records one (`Expected` in `check/walk/scalar.rs`): `tests/test_refinements.py` counts the bound's `repr` calls, and a hundred passing checks make none. A constraint is decided without its code and expectation, which `explained` builds only for a failure a walk that explains records, and the walk's context is read through the frame rather than copied onto the stack once per constraint: a thousand integers under two bounds cost 11% fewer instructions, a thousand strings under two length bounds 17%.
- **An order bound over a float compares two floats.** An exact `float` under an operand a float holds exactly, an exact `float` or an exact `int` up to `2^53`, is the two read where they lie, and no Python runs (`floats_compared` in `check/walk/scalar.rs`, with the operands read once a validator by `float_operand` in `check/index.rs`). A thousand floats under one bound read 69% fewer instructions on the profiled CPython 3.15 wheel, `--binding-refined-float` 52% on the build without a profile, and a record of two such fields beside a refined `int` 18%. Any other value pays a load and a comparison, and a test holds the reading to the comparison over every bound, a value of every kind and an operand of every kind. A float the two floats admit is admitted where the constraint is read, with no call into the bound's own reading, which a refusal and every other value still take: a record of three refined fields reads 0.7% to 1% fewer instructions on the profiled wheels than the 0.0.30 wheels, as `scripts/perf_inspect.py count` reads its `refined_fields` shape.
- **An error the walk answers with is dropped out of line.** Dropping one asks whether the thread is attached to the interpreter, a thread-local the extension reaches through a call into the dynamic linker, and inlined into a loop, the compiler takes that address ahead of the loop, on the path where nothing raises. So the errors a constraint and an attribute record answer with are dropped in functions of their own (`set_aside` and `predicate_raised` in `check/walk/scalar.rs`, `attribute_missing` in `check/walk/record.rs`): in the extension, a thousand integers under two bounds cost 2.8% fewer instructions on 3.12, 3.14 and 3.15, strings under two length bounds 3.6%, and a list of dataclasses 1.2%. The instruction gate's workload is an executable, which reads a thread-local without the call, so it sees none of this; a probe of the built extension does.
- **A fast walk asks in the frame it holds.** A walk carries two buffers, for where it is and what it has found, and a fast walk writes neither; each is still a value with a destructor. A union's branch is walked in the union's own frame (`check_union` in `check/walk.rs`), and a mapping's scan keeps one fast frame for every entry its clauses are asked of (`covered` in `check/walk/record.rs`), rather than a pair built and dropped per branch and per key: a recursive schema's descent costs 10% fewer instructions that way (`--binding-memo`). A record's deciding pass reads over its caller's buffers in a fast frame, and keeps its progress only where the walk explains a record it refuses (`check_keyed_map`): a list of two hundred records costs 4.8% fewer instructions that way, and a record the walk reaches alone 2.9%. The scan reads the frame's context where it lies, asking each half of a clause as a record asks a field (`field_holds`), rather than copying the context once an entry. Where a fast walk has no frame to hold -- `is_valid` and `is_valid_json` themselves, a mapping's scan, a parsed object -- its pair is an `Unwritten` one, never dropped because it never owns anything: `is_valid` on a scalar costs 6% fewer instructions that way on CPython 3.15, `in` 9%, and the instruction gate's call boundary 13% (`--binding-boundary`).
- **The context a level hands on is seven words.** It holds the pool, the definitions, and one reference each to the validator's index and the call's state (`Ctx` in `check/ctx.rs`), and a table or a cell lies at a fixed offset of what is referred to, so each is read with the loads a reference of its own would take. A walk that descends copies less a level: on the CPython 3.12 PGO wheel a list nested twenty-five deep costs 12.9% fewer instructions, a scalar 5.4%, a literal 4.8% and a JSON document 1.5%, and the deepest walks fit a thread of 844 KiB. On the instruction gate the call boundary reads 1.9% fewer and a recursive schema 1.2%.
- **The recursion trail is a stack, reserved on first use.** Entering a reference pushes a `(value, definition)` pair and leaving pops it (`Trail` in `check/ctx.rs`), so nothing is hashed. The first level reserves `FIRST_TRAIL` pairs in one small request, and a walk that enters no reference allocates nothing (`--binding-recursive`).
- **A leaf is decided by a value's type and number.** A union, meet or complement of scalar kinds and of refinements of `int` and `float` by bounds and steps -- JSON Schema's `integer` and `number` -- is specialized to each exact builtin type once a validator (`LeafPlan` in `check/index.rs`): a constant, or the test of the number left when each kind folds away. A list of one reads each element's type and, where the type leaves it open, its number (`leaf_list_read` in `check/walk/sequence.rs`), and walks any other element in the walk's own mode. The list arm asks it behind a test of the index's one word, so a validator holding no reading keeps the other readers' tail calls, and a union of scalar kinds, which has a reader of its own, holds no plan. A parsed array of one is read by each item's tag and number (`leaf_array_read`). On the profiled CPython 3.15 wheel a list of a thousand integers against `integer` costs 92% fewer instructions, a thousand floats against `number` 83%, and a document of a thousand integers 67%, the parse included; a test holds the reader to the general loop's verdict, stop, moves, fatal signal and report in every mode. A leaf over `float`s that is order bounds alone is held as the interval they admit (`Interval` in `check/index.rs`), two comparisons where the bounds were each a test through the leaf's tree: a thousand floats against `number` count 44% fewer instructions again, and a list or a mapping of a tree answers an exact `float` by the interval at once. A mapping of `str` keys to a leaf is read the same way (`leaf_dict_read`): valgebra-jsonschema's `str -> integer` map of a thousand entries checks in 12.5 us where the scan took 31. A leaf may hold a reference to a tree of scalars (`Leaf::Tree`), the JSON values a translation meets a keyword's guard with: a scalar is the tree's leaves' answer, a list or a dict the tree reads on is walked, and the reader takes it where the trail is below its bound and no memo is armed (`leaf_reads_here` in `check/walk/scalar.rs`). On the profiled CPython 3.15 wheel, a thousand integers against `if: integer, then: minimum   0` check in 7.3 us where the walk took 60.7 (1,410,105 to 165,119 instructions a call), against `minimum: 0` with no `type` in 7.4 where it took 42.8, and against `not: string` in 2.35 where it took 19.9 (`list_guarded` 89% fewer instructions).
- **A tree of scalars is read by each value's type.** A definition whose union holds only leaves refusing every list and dict, a list of the definition and a mapping of `str` keys to it -- the values `json.loads` returns, `int |   list[t]` -- is asked each value's exact type once (`tree_member` in `check/walk/tree.rs`, over `TreePlan` in `check/index.rs`), where the walk spends a reference, its pair on the trail, the union's level and a branch per member around the same question. On the profiled CPython 3.15 wheel the JSON values over two hundred records of every kind of JSON value cost 73% fewer instructions and `int | list[t]` over a tree twelve deep 61%, and `--binding-recursive` 46% on the build without a profile. A value of no exact builtin type, one near either bound and one inside itself are handed to the walk where it would have reached them, a walk that explains or settles a complement reads the definition generally, and one with a memo armed reads its scalars alone, noting the reach their walks would note; a test holds the reading to the walk's verdict, stop, moves and fatal signal. The index holds the plans of leaves and trees behind one word, and the reference's arm asks whether it holds any and whether the value is a Python one, so a validator holding none pays a load and a comparison a reference.
- **A list or a mapping of a tree is read by each value's type.** `list[J]` and `dict[str, J]`, which a JSON Schema translation meets every array and object with, read each value as the tree's reading does at the value's reference, the bounds asked once for the container (`tree_list_read` and `tree_dict_read` in `check/walk/tree.rs`). On the profiled CPython 3.15 wheel `list[J]` over a thousand integers takes 2.5 us where the reference's arm took 6.8, and `dict[str, J]` over a thousand entries 6.2 us where it took 13.2: each reader keeps the type of the last value its leaf admits whatever the number, so a value of that type is one comparison of its type pointer. The list arm asks it behind the index's word, since a list of a reference in a validator holding no reading paid the reader's call: the memo's shape read 3.5% dearer without it, and reads 1.6% dearer with it on the build without a profile, a list of records 0.9% and a list nested twenty-five deep 0.5%; on the profiled wheel every shape counts within 0.5%.
- **A kept walk reads a tree's scalars by type.** A JSON Schema translation meets each array with `list[J]` and a list of its items, each record reaching `J` too, so the meet's second member is walked with the memo armed, and there every reading of the tree declined: each value cost a hash insert and the general walk. The readings read a scalar there by its exact type, noting the reach its reference's walk would note, and leave a container to the walk, which keeps it for the deeper meets that reach `J` at it (`kept_scalar_read`, `kept_list_read` and `kept_dict_read`). On the profiled CPython 3.15 wheel valgebra-jsonschema's array of two hundred records counts 25% fewer instructions a call and checks in 52 us where it took 67, its `if`/`then` array 29% fewer and 64 us where it took 96, and its tagged `oneOf` 21% fewer; a chain of sixty objects against a recursive `$ref` checks in 22 us where it took 25. The kept list and mapping readers take five and four arguments, asked once the mode and the prefix are read: asked with the prefix where the reading declines, they cost the plain `list[J]` reader an instruction an element.

### Sequences and sets

- **A sequence of one scalar kind is a loop per kind.** `scalar_list_matches` in `crates/valgebra-py/src/check/walk/sequence.rs` reads the element kind once and runs a loop whose type test is a constant, compiled out of line from the rest of the sequence walk so that an edit elsewhere does not move its register allocation (`--binding`). A set, a frozenset and a parsed JSON array take the same reading, a set with a scan per kind in both the deciding and the explaining walk (`--binding-set`). A list of one scalar kind or `None` has a loop per kind too, both tests constants inside it (`nullable_list_matches`; `--binding-nullable`): a thousand-element `list[str | None]` costs 80% fewer instructions than through the union's branches on CPython 3.14 and 3.15, under `is_valid` and `validate` alike, and 72% on 3.12.
- **A list is read through a snapshot where that pays.** Reading a list element hands out an owned reference, a count written on the element twice; a tuple copy pays those writes in two loops inside the interpreter and none in the walk. `snapshot_pays` decides it per interpreter and per length, as [the margins above](<#one-of-those-margins-moves-with-the-interpreter>) describe. The instruction count of a snapshot reading is *higher* than in place -- the copy is instructions, and the stall it removes is not -- which is why the wall clock decides this one. Before 3.12 allocating the copy may run a collection, and a finalizer it runs may empty the list under the copy, so on 3.11 the copy holds the collector off for its own length: three calls, about three hundred instructions a list, 1.4% to 1.6% of a thousand integers on the profiled wheels.
- **A tuple's elements are borrowed**, because a tuple cannot change while the caller holds it; a list cannot be read that way. On CPython, `PyTuple_GET_SIZE` and `PyTuple_GET_ITEM` read a tuple's storage whatever its type overrides, so every tuple, subclass or not, is read where it lies and its type is asked nothing: a `NamedTuple` validates at what a tuple does (`--binding-subclass`). PyPy's `cpyext` answers those accessors through a subclass's own `__len__` and `__iter__`, so there the walk asks the type whether it inherits both and copies any subclass that does not. A length bound asks the type whether its `__len__` is the tuple's own on every interpreter, since it counts what the value holds rather than what an override answers.
- **A tuple of scalar positions is one type test a position** (`scalar_positions_tuple_matches`), and a list whose element is a union of literals, one class, a tuple of scalars or a named tuple of them is read through that union's table, the type-pointer test, a test of each position, or the class's pointer test and a test of each position, with the positions read once for the list (`element_list_matches`). An element the test does not settle is walked, which may run Python, so the list is read in place unless a snapshot settles it entirely. A thousand `datetime.date` values cost 76% fewer instructions than through the general loop, a thousand `tuple[int, str]` 61% on 3.12 and 3.14, 68% in the 3.14 PGO wheel, and a thousand two-field `NamedTuple`s 76% on 3.12, 3.14 and 3.15, 81% under `validate`. A list of refinements calls each element's own check, with the level the walk opens for an element held across the list (`refined_list_matches`): a thousand integers under two bounds cost 12% fewer instructions, and a thousand strings under two length bounds 19%. Deciding over a base of `int`, `float` or `str`, its kind is read once and has a loop of its own (`refined_scalar_list`): strings under a pattern read 7.4% fewer instructions on the profiled CPython 3.15 wheel. One pattern, alone or beside length bounds, is read from the index once for the list, and an exact `str` is its text matched against it (`pattern_list`): two hundred strings under one pattern read 15% fewer instructions on the profiled CPython 3.12 wheel than with the pattern found at each element, as `scripts/perf_inspect.py   count` reads its `pattern` shape. Order bounds on an `int` whose operands a machine word holds are one range read once for the list, and an exact `int` that fits a word is compared with it where it lies (`machine_range_list`): a thousand integers under one bound read 74% fewer instructions there, and 77% on the build without a profile (`--binding-refined`). A value past the word is read by the comparisons, once its read has raised, and that ends the range for the list. Order bounds on a `float` whose operands a float holds are one interval read once for the list, each end open or closed, and an exact `float` is compared with it where it lies (`float_range_list`): a thousand floats under one bound read 43% to 49% fewer instructions on the profiled wheels of CPython 3.11 to 3.15 than the 0.0.30 wheels, which read each float through the constraints' loop, as `scripts/perf_inspect.py count` reads its `refined_float` shape. Length bounds on a `str` are one range of code points read once for the list, and an exact `str`'s length is compared with it (`length_range_list`): a thousand strings under a minimum and a maximum length read 77% fewer instructions on the profiled CPython 3.15 wheel. Any other element is its own check. A meet of `str` and its length refinements is the same one range (`text_meet_list`), whatever else the validator holds: valgebra-jsonschema's array of a thousand strings under `minLength` and `maxLength`, `list[str & MaxLen & MinLen]`, checks in 3.7 us where the walk through the meet took 24. A list of records reads each element by its record's check, inlined into the reader, with that level held the same way (`record_list_matches`): two hundred three-field `TypedDict`s cost 7.5% fewer instructions on 3.12 and 3.14. What its node says of every element, its plan and what its clauses admit, is read once for the list (`RecordReading`), which is 6.6% of that shape's instructions on the build without a profile (`--binding-record-list`). A list of dataclasses walks an element of exactly the class as the record of its fields, without dispatching the meet, the class and the record around it (`class_record_list_matches`): 12% fewer instructions for a hundred five-field dataclasses, in both modes.
- **A scan holds its container's lock once on a free-threaded build.** `PyO3`'s list and dict iterators take the container's critical section around every step, each a re-entry of the section the scan already holds; their `find_map` takes it once, and the free-threaded build's list and dict scans step inside it. In the 3.14t PGO wheel, `is_valid` on a hundred-entry `dict[str, int]` takes 18% less time, and on a thousand-element `list[tuple[int, str]]` 19%. Under a global lock both scans keep their hand-stepped loops: through `find_map`, a `list[int]` read in place on 3.14 costs 59% more instructions, and the record shapes the dict scan is inlined beside 1.4% more.

### Records

- **A closed record probes the keys it declares.** Membership is settled by asking the dict for each declared key and counting: the value belongs exactly when each key it holds matches its field and it holds nothing else, which the dict's own length says, since a dict cannot repeat a key. A declared key is interned with the validator and carries its hash, so each probe is the probe alone, and a key is resolved the way Python resolves one -- a `str` subclass, or a key of another type, is the field exactly where indexing the dict finds it, in this reading and in the scan beside it.
- **A field is read beside its key.** The record's declared fields and its plan's interned keys are one length, so the loop steps both, with no bound test and no `Option` a field (`keyed_map_asks_for_its_keys`): a fifty-field record reads 8% fewer instructions on the profiled CPython 3.15 wheel, and 2.2% on the build without a profile (`--binding-record`).
- **The probe is the floor for this shape.** Profiled under callgrind on CPython 3.12, fifty probes of a fifty-field record are about 143 instructions each and 64% of the accepting call. Iterating the dict once and resolving each key by name instead measures 47.9% dearer: an iteration step increments two reference counts, casts and decodes the key and hashes it, where a probe on an interned key carries its hash already.
- **Interned keys meet on a pointer, and Python interns most of them.** A dict probe compares the key it is given with the key it holds by pointer before it compares hashes or bytes. A dict written as a literal, one built from `**kwargs` and an object's `__dict__` all carry interned keys, so a record walk over them settles each field in one comparison: on a fifty-field record, interned keys read about 28% cheaper than keys that are not (`--binding-keys` against `--binding-record`). Keys parsed from JSON or built with f-strings are not interned and take the hash-and-compare path, which is what the figures on this page are measured over; `sys.intern` on the keys of a dict you validate in a loop is worth trying if that loop is your bottleneck.
- **An open record is read by its keys too.** A `TypedDict` admits keys it does not declare through the clause `str: anything`, and what that clause says about an undeclared key -- it is admitted exactly when it is a `str` -- can be said without reading its value (`Undeclared::of` in `crates/valgebra-py/src/check/walk/record.rs`; `--binding-open`). A record whose clause reads a key together with its value -- the `str: J` a JSON Schema translation writes for `additionalProperties` absent -- is read by its keys as well, and where the value holds a key it does not declare, those keys alone are scanned against the clause (`undeclared_held`): a list of two hundred records `{id: integer, name: str, tags: list[str], str: J}`, as valgebra-jsonschema writes an array of objects, reads 21.5% fewer instructions on the profiled CPython 3.15 wheel (16.97 to 10.68 us), a list of two such records' tagged `oneOf` 26.9%, and a `$ref` tree of 511 such nodes 17.1%.
- **A dataclass's attribute names are interned once per validator**, so `getattr` is handed an object the interpreter already holds. The object is read borrowed, as the walk holds it, so reading a record writes no reference count on it, and a scalar attribute is its type test asked in the loop over the attributes, the level it needs read once for the record (`check_attr_record` in `check/walk/record.rs`): a list of dataclasses costs 2.7% fewer instructions that way on CPython 3.12 and 3.15.

### Unions and literals

- **A union of literals is a table.** A union whose members are all literals -- a `Literal["a", "b", ...]`, a discriminator -- is compiled once into value-keyed sets, one for its integer literals and one for its string literals (`UnionPlan` in `crates/valgebra-py/src/check/index.rs`). An exact `int` or `str` value is one set lookup, so the cost stops growing with the number of literals. The integer set is consulted only for an exact `int` (never a `bool`) and the string set only for an exact `str`; any other value -- a `bool`, a `float`, `None`, a subclass instance, a JSON value -- falls back to the scan, which remains the single source of truth, and tests hold the two to one verdict over the cross-type cases. The table also keeps its constants' addresses, so a value that is the constant itself is answered without reading its text: a thousand-element list of four string literals costs 37% fewer instructions than reading each value's text.
- **The closest branch is searched within a bound.** A failing union reports the branch whose first failure lies deepest, and the search re-walks at most `CLOSEST_BRANCH_PROBE_LIMIT` branches, so a very wide union bounds the cost of its own report.

### JSON

- **`is_valid_json` walks the parsed document in place.** The walk reads a value that is either a Python object or a parsed JSON value, so a document is checked without building Python objects for it, except the value at a node that compares it with one: a literal, an instance or object check, a refinement's comparison or predicate. The two sources run one walk and stay equivalent by construction, which a property test holds over random schemas and documents ([the JSON page](<https://ppigazzini.github.io/valgebra/guides/json/index.md>) has the figures).
- **A closed record reads a document's keys through its plan, once.** Each key of the parsed object is resolved through the record's name-to-position plan and every declared field's value gathered before any is checked, because a repeated key means the document's last entry, as `json.loads` has it. The gathered table sits on the stack for a record of up to `FOUND_ON_STACK` fields.
- **A parsed object's keys are strings.** A clause keyed by `str` therefore admits every key of a parsed object, and covering a free-form section is a check of its values alone. An object of up to `SMALL_OBJECT` entries is covered where it lies -- an entry is the one the document means exactly when no later entry repeats its key -- and a wider one through a table of last values.
- **A length bound counts a parsed container where it lies.** An array's length is its item count, and an object's is its distinct keys, counted by the same two readings (`distinct_keys` in `check/walk/record.rs`), since the dict `json.loads` builds holds a repeated key once. The bounds are asked before the elements, and a document runs no code that could change it, so a refinement whose every constraint is a length bound builds nothing to ask them again (`parsed_for_constraints` in `check/walk/scalar.rs`). Two hundred records under `MaxLen(8)` cost 65% fewer instructions than building each one into a dict, once to count it and once to ask the bound again. The building is out of line, and a list of refined Python integers costs 1% fewer for it.

### Reporting a failure

- **`validate` is one explaining walk**, and the cheap readings serve it. An explaining walk records nothing of what it admits, so an element that passes its type test is answered by the test (`admitted_quietly` in `check/walk/scalar.rs`), and a sequence of scalars is read as its tests, an element that fails being walked at its own position (`list_explained`, `tuple_explained`). `validate` on a thousand-element `list[int]` that belongs executes about a fifth of the instructions the general element loop takes, and within a twentieth of what `is_valid` takes: each scalar kind has a loop of its own in the explaining reader as in the deciding one, which on CPython 3.14 and 3.15, where the list is read in place, is a fifth of `validate`'s instructions on a list of integers and 15% of its time. A tuple of one scalar kind takes a test per kind the same way (`homogeneous_tuple_explained`), and `validate` on a thousand-element `tuple[int, ...]` costs 46% fewer instructions than through the reading of each position's schema.
- **A refused list is read once up to where it fails.** Where the explaining walk reads a list through a snapshot, the snapshot's test stops at the first element it refuses, and the walk reads the list in place from that element on (`list_explained` in `check/walk/sequence.rs`): nothing has run before it, so the elements the test passed are not read again. On CPython 3.12, `validate` on ten thousand integers refused at the last element costs 41% fewer instructions than read in place from the start, refused at the middle 22% fewer, `fail_fast` there 28% fewer, and a list of one class refused at the last 42% fewer. A list that belongs costs what it cost, and one refused at its first elements within a few percent of it: a `list[int | None]` refused at its second element, 2.9% more. CPython 3.14 and 3.15 read the list in place from the start, where no snapshot pays. Reading only the elements the snapshot refused is not taken, since the walk of one may change the others (`docs/dev/walk.md` in the repository).
- **A union explains no branch for a value it admits.** Only a refused value's report reads the branches that did not match, so a branch that fails at the union's own location -- a scalar, a literal, a container of another kind, a class -- is decided by its test (`decided_quietly` in `check/walk.rs`), and a record branch by its deciding pass, its explaining pass waiting until no branch has admitted the value (`explain_union`). `validate` on a hundred values of a tagged union of three `TypedDict`s costs a fifth of the instructions it costs with each refused branch explained in turn, close to what `is_valid` costs, and a union of dataclasses about as much, on CPython 3.12 and 3.14 alike: the report a refused branch builds summarizes the value, and a dataclass's summary is its `__repr__`, Python code. Tests count the reprs a member's report would run, and hold a refused union's report to the one its chosen branch gives alone.
- **The explaining walk resumes where the deciding walk stopped**, as [the closest races](<#the-closest-races>) describe: a field the first walk passed has no violation to report (`--binding-explain`).
- **A report builds each key and string once.** The keys of the error model are interned, a violation's message and path are built once and shared between the error item and the attribute that mirrors it, and a path segment shares the field name the schema already holds.
- **A value summary is bounded while it is built.** Every violation summarizes the value it is about, and a container is rendered through `reprlib` under a depth and width bound (`BOUNDED_REPR` in `crates/valgebra-py/src/errors.rs`) rather than rendered whole and cut, so reporting on a value nested twenty thousand deep takes about 23 us. A value small enough to print renders exactly as `repr` would.

### What a relation between two validators costs

`is_subtype_of`, `relation_to` and `is_equivalent` are not the membership walk, and they have a cost of their own with two clear levels. A pair a **rule** decides costs about a microsecond: the rules recurse over the two schemas and answer from their shapes. A pair the rules decline goes to the **set representation**, which lowers both sides into automata and takes tens to hundreds of microseconds. Inside the core the two answers to one question are about three orders of magnitude apart -- `scripts/perf_gate.py --decision-rules` and `--decision-sets` ask one corpus of each, and `scripts/perf_budget.json` holds both counts -- and a call through `relation_to` adds its own fixed cost to either. That gap is the reason a rule that stops declining is worth writing.

Which pairs land on which side is the interesting part, and it moves. Most do not reach the sets: a mismatch of kinds, a record missing a required key, a sequence of the wrong arity, a subject outside a refinement's base. What still reaches them is a schema whose atom only the bindings can read on one side and a structure on the other -- a class deriving from no builtin, a complement as the subject -- and a bound that has to be *compared* rather than matched, such as a list against a length-bounded list of the same element.

- **The cheap questions are asked first.** A node is a subtype of itself, which a pointer comparison answers before anything else; a universe on the right is read off the region set the query already holds; a schema below a union is first looked for among the union's branches, which keeps widening a literal union linear in its members; and the readings that refute a pair no rule places are asked in the order they cost, the walk of both subtrees last (`crates/valgebra-core/src/decision.rs`). A kind refutation reads the subject's whole kinds first, since most subjects hold none and the supertype then goes unwalked (`spills_a_kind_into`).
- **The set representation is asked only where the rules are silent.** Both deciders answer in three values, so the descriptor is asked where the rules answer *unknown*, never where they proved the answer.
- **Records compare by a cursor.** Two name-sorted field lists are walked together, each lookup one ordering comparison, with no table built per call (`FieldCursor` in `decision/records.rs`); a record whose fields repeat one schema asks that goal once.
- **Every query spends a work budget** (`spend` in `decision.rs`), and returns the conservative answer once it is spent, so a deeply nested Boolean combination stops rather than running unbounded.
- **A query carries its state behind one pointer.** The oracle, the definitions, the budget, the trail and the `visiting` list are one context per query (`Cx` in `decision.rs`), handed down by reference: a rule's call passes one pointer, and an emptiness question a goal asks reads the query's `visiting` list rather than starting one. The meets being unfolded stay off it, on a list only an unfolded meet reaches, since a field of the context is built and dropped by every query.
- **The set representation shares what it does not edit.** An automaton holds its edge guards and its word automata by handle, a complement of a minimal automaton keeps it minimal, and a question about which kinds a descriptor reaches is read off its components (`Descr::within`, `Descr::reaches` in `descr/mod.rs`) rather than answered by building a meet and testing it.
- **A word automaton is minimized by halves.** The states no word tells apart merge once blocks of states are cut by the transitions read backwards, and only the smaller part of each cut is queued to cut by next (`equivalent_states` in `descr/regular.rs`, Hopcroft's algorithm): `k n log n` work over `n` states and `k` byte classes. Signing every state afresh each round reaches the same partition and spends a round per state on a chain, which is what a literal is: a literal of four thousand bytes takes about 1.5 ms to build on a release build, where signing every state each round takes 603 ms, and a product that keeps its chain is minimized again at the same cost. `--decision-sets` reads 6.12% fewer instructions, the signatures the rounds allocated.
- **A pattern is built once a thread.** A lowering reads a schema's patterns and length bounds again for every difference a relation asks, so a thread keeps each word automaton it built under the text it was built from, a refusal among them, up to sixteen mebibytes (`RegularSet::compile` in `descr/regular.rs`). Two JSON Schema documents translated into validators, holding three patterns and three length bounds between them, ask for their automata 322 times and build six, which hold 85,678 bytes: the relation declines in 0.17 s on a release build, against 4.2 s when every request builds. A pair whose one pattern the build refuses decides in 0.46 s against 2.14 s, since a refusal spends the most of any build. The instruction gate's decision workloads read no more than before.
- **A pattern the oracle walks is compiled once a query.** A literal is asked of a pattern by walking its constant through a schema no validator built an index for, so a table of strings compiled the pattern once a constant: 1,024 strings against the alternation of the same words took 1.4 s on a release build. The query keeps each pattern it compiled under its text and drops them when it is answered (`matches_unindexed` in `check/index.rs`), and the pair takes 2 ms. An oracle that walked nothing, which is most relations, drops with no thread-local read (`walked` in `oracle.rs`), and a relation reads its answer off the oracle by reference, its size being past what a move does inline.
- **A value the last asking reads of a schema is read once a query.** The asking that reads a pair's leaves lowers each refinement, meet and complement the rules leave open, alone, for a value, and a query asks the same ones again: one question over drawn JSON shapes asked the sets of a meet of nine nodes 3,609 times, and read for 94 ms on a release build against 6.2 ms without the reading. The query holds each answer under its number (`Cx::reads_a_value` in `decision.rs`) and charges the steps each time it is asked, so the memo moves no answer, and the question reads 8.7 ms. The instruction gate's decision workloads read within 0.4% of the last release's.
- **A length bound costs a state an element and little else.** A bound over a list is an automaton of one letter repeated, so the letter is held by one handle and asked whether it takes every value once (`chain` in `descr/symbolic.rs`); a chain whose letters all hold a value is minimal as built and skips the merge; a row with no guarded edge leaves everything, so meeting its else edge is the guard itself (`Rest`); a product keeps the rests and the meets it has asked for the pairs to come, since a chain repeats its rows (`Rests`, `Met`); and a side that is the whole language or the empty one is answered without a product. A bound of forty elements over `list[int]` lowers on 135 units of the allowance, so two bounds are compared up to the state bound, 2,046 elements, with allowance to spare; `MinLen(4000)` refuses in 4 ms against 1.2 s. `--decision-lengths` reads 88.31% fewer instructions and `--decision-sets` 21.80% fewer.
- **A sequence automaton's merge starts from three distances, and signs only the states that share a block.** Before its first round, each state is put in a block by its distance to an accepting state, its distance to a rejecting one, and the longest walk it can take while acceptance stays in reach (`seed` in `descr/symbolic.rs`). States the merge joins agree on all three, so the start changes no table; what it changes is the rounds. From one block, the rounds part a chain a state per round, and a chain is what a length bound is; from the distances its states are apart before the first round, a lower bound's by how far each is from accepting and an upper bound's by how far each can go. A block of one state cannot split, so a round signs only the members of larger blocks (`refine` in `descr/automaton.rs`): two tuples of a thousand positions that differ only at their last take a round per position, which the distances do not save, and their union reads 1.06 billion instructions against 2.11 billion when every round signs every state. `MinLen(1000)` over `list[int]` lowers in 1.8 ms against 87 ms on a release build, `MaxLen(1000)` in 1.6 ms against 104 ms, and `MinLen(500) ⊆ MinLen(1000)` decides in 5.9 ms against 146 ms. `--decision-lengths` reads 19.85% fewer instructions and `--decision-sets` 0.88% fewer.
- **A union's members are joined in rounds.** A lowering reads every member of a union and joins them two at a time, each round halving the list (`joined_in_rounds` in `crates/valgebra-core/src/lib.rs`). A join admits what it holds against what it has kept, so joining the whole so far with each member in turn reads the cube of the width, and a member past the bound on a line's atoms retries the full line. A relation between two unions of 2,048 tagged records, which the node bound refuses, declines in 37 ms on a release build, where the fold takes 5.9 s, and `--decision-unions` holds it: the fold reads 1,825 times the instructions. Up to three members, those are a fold's joins, and they hold no list, since a list of descriptors is a request past the allocator's bins whose consolidating costs more than the union it would hold.
- **A complement is built only where it is read.** Most sets hold a kind or two, and a complement builds a top for every kind a set misses. Whether a letter takes every value, and whether an else edge is dead, ask only whether a complement holds a value, and a kind holding no line answers that with nothing built (`leaves` in `descr/mod.rs`). A difference reads only the kinds its subject holds (`minus`), and a product holds what an edge's neighbors take in place of their complement. A meet starts from its first member rather than from every value. The relations of the JSON Schema containment suite read 37% fewer instructions on a release build, `--decision-sets` 29.82% fewer and `--decision-lengths` 66.37%, and what a relation keeps of its allowance decides a few a dearer reading declines.
- **A pair the sets read whole is not read again.** Their reading of a pair spends no step, so it reads alike however often it is read. Neither the last asking's root nor a second asking lowers it again, and `dict[str, int]` below a dict of 4,096 literal keys reads 761 million instructions where it read 1.87 billion, a release's being 719 million.
- **A wide union asks the rules before it lowers a branch.** A branch the rules refute is one the sets never prove, and what the root keeps of that fits 64 branches, so a wider union lowered the subject once a branch: `frozenset[Literal[0, ..., 511]]` below the union of the 512 `frozenset[Literal[i]]` read 8.9 billion instructions. Asked of the rules first it read 350 million, with no answer moved over the families and the instruction gate within 0.05%.
- **A product of two automata is charged by its table.** One unit of a build's allowance bought a product of any size, thousands of entries for a Unicode class, so a pattern over `\w` beneath four lists read 3.7 s before a bound declined the whole. Charged by its entries, the reading of the whole refuses early, the last asking reads the leaves, and the pair answers in 0.5 s, with no answer lost over the word families.
- **A table of constants beside its kind is the table.** A translation from JSON Schema writes an `enum` of strings as `str` met with the literals, and the relation between two read as a product of the automata of their words: 60 words against 400 took 79 ms, where the two tables' own relation takes 0.2. A meet whose other members hold each constant is read as the table, in 1.6 ms, and a meet holding none pays a test a member.
- **A supertype proved empty needs no difference.** `int` below a recursive attribute record with no value read for up to a second, on the second reading's unfoldings, for a question `is_empty` answers at once. The relation reads the supertype's emptiness first, where its shape can hold none and it holds a reference.
- **A leaf is read by the sets last, and alone.** A goal the rules decline, with no reference on either side, is the sets' to answer where the pair's own reading stopped at a reference beside it. Asked of every such goal, it cost the relation matrix ninety-six times its instructions, since a goal declined on the way to another rule's answer is the common case, so it is asked in a last asking of a pair everything else declined, and only of one holding a constructor or a reference. Lowerings are charged steps, so an asking reads at most sixty-four.
- **A step's table is charged by what it holds, and shared rather than copied.** An operation over a `MultipleOf`'s table reads a list per residue, so one unit of a build's allowance bought up to 4,096 lists and each automaton edge kept them. A unit per thousand residues and spans leaves every table under that at no charge, and two list bounds over a step of 4096 decline in under a second, where they read for a minute, kept gigabytes, and ended a process short of memory. A descriptor holds its integers' and floats' tables by handle, since no operation edits one: `--decision-matrix` reads 0.80% fewer instructions and `--decision-sets` 1.11%.
- **A class an operation hands back is fitted as it stands.** An operation over a step's table reads each residue's spans and fits the result to that residue, a search per end for a float of the class. A class is mostly nothing or every float of its residue, so the result is mostly one of the two lists it was made from, each fitted already (`refitted` in `descr/floats.rs`): `--decision-steps` reads 10.8% fewer instructions.
- **A descriptor is equal to itself at its own address.** A product of two unions sorts what it keeps, and its atoms hold their fields by handle, so most of what a comparison reaches is one allocation read on both sides, walked to its depth field by field. The order reads the address first (`Descr` in `descr/mod.rs`): `--decision-unions` reads 1.12% fewer instructions, and a relation an undecided meet of a recursive schema reads in 13 ms takes 6.7.
- **A language is empty where no state accepts.** Every table a set holds is minimal or the complement of one, so a word reaches every state, and whether the language holds a word is a scan of the accepting flags (`RegularSet::is_empty` in `descr/regular.rs`), where a walk asks a queue of each table a kind holds. A float set read at its own period is read as it stands (`split_at` in `descr/floats.rs`), since a set built at a period holds its classes fitted, and fitting them again finds what it holds. `--decision-steps` reads 23.51% fewer instructions and `--decision-keys` 8.53%, and the containment relations 1.9% fewer.

**A pair's constants are read once per validator, not once per question.** Relating two validators pools one's constants into the other's, and the key a constant is pooled by is read out of the interpreter. Each validator keeps the keys of its own pool from the first relation it is a side of, so asking about a pair again reads neither pool. Relating two tables of ten thousand codes costs 5.4 million instructions that way, 2.3 million of them the rules' own answer; reading the keys afresh for each question costs 15.0 million. Two validators built alike compare equal in one pass over their members and their recursive definitions, each definition against the one at its own index. Two whose definitions were numbered apart take a second reading only where each holds two definitions or more and their bodies agree as multisets, and that reading pairs the definitions in the order construction numbered them before the trees are read, so each body is read once (`schemas_equal` in `crates/valgebra-py/src/equality.rs`). A validator keeps its hash once computed, as a `frozenset` does.

**A refutation about a class reads the class.** It stands on a direct instance of the class, and what that instance can carry is read off the namespaces of the class's `__mro__`: which names each defines, whether each is a slot or a data descriptor, and whether instances carry a `__dict__`. The namespaces of `object`, the builtins a kind is read from and `BaseException` are static types no assignment reaches, so each is read once for the process. A class's own namespace is read once and kept: an assignment to the class between two relations moves what the second one reads, so the next relation walks the namespace and takes the kept reading only where it holds the same names, in their order, each read as the same member, which is the reading a fresh one would build. The walk spends what reading the namespace's items spends, and no copy of a name, no sort and no `hasattr` on a builtin type: a refutation between two dataclasses reads about 40% fewer instructions than with its classes read afresh, on CPython 3.15 and 3.12, as `scripts/perf_gate.py --binding-relation` counts it. A kept reading holds strings alone, so a class a program drops is freed as it would be.

There is no wall-clock gate on this, and that is deliberate: a relation's wall-clock cost is a property of the pair, and pinning one would be pinning a number the next rule changes. The instruction gate covers the decision workloads `crates/valgebra-core/examples/` holds -- one for each path a relation takes, which `MODES` in `scripts/perf_gate.py` names -- and those are what a change to the rules moves. What the bindings read off a class is no rule's, and no decision workload reaches it, because their classes are identities with nothing behind them; `--binding-relation` relates two dataclasses through `relation_to` and counts it.

### The schema representation

- **A node carries its children by a shared handle.** A child is a shared pointer and a node's lists are shared slices, so carrying a subtree across a rebuild is a reference count rather than a copy; a field's name is an `Arc<str>`, atomic because a validator is shared across threads on a free-threaded interpreter.
- **A transform hands back what it was given when nothing changed**, so opening a schema that holds no record, or shifting the half of a composition whose indices do not move, returns the caller's own handle.
- **An operand whose indices do not move is not walked.** Composed into a pool and a table that hold nothing yet, or into a table holding its definitions at its start with its constants at their slots, an operand is the handle it holds (`Placed::Kept` in `crates/valgebra-py/src/build.rs`), where the remap would walk every node to find that none moves. A record nested sixty deep, each level met with the JSON values, composes in about half the time, since each level paid that walk over the levels below it, and `--binding-compose`, sixteen such levels, counts 21% fewer instructions than with the walk.
- **A composition moves the incoming half in one pass.** Its definitions are found as a block where the table already holds them, or appended whole, and either way one shift moves every reference to them in the pass that moves its constants; only a placement that finds some of them and appends the rest renumbers the tree a second time (`place_definitions` in `crates/valgebra-py/src/build.rs`).
- **A node built twice is one node.** A member list, field list, clause list or child built twice is one handle, held in a per-thread, direct-mapped table of weak references (`crates/valgebra-core/src/ir/intern.rs`). Sharing is decided by a test stricter than structural equality -- the same allocation, or the same value in every field -- so a caller cannot observe which handle it got; and the table is what makes two equal schemas cheap for a relation to compare.
- **Two handles of one node compare at once, under the order as under equality.** A union and a meet keep their members sorted, and `Schema`'s order asks whether two nodes are one allocation before it reads them (`impl Ord for Schema` in `ir.rs`), as `Arc`'s equality does. A subtree shared many times is a tree many times its size, and an unfolded fixpoint is one: sorting a union of its prefixes walked each shared child as the whole tree, where a relation over forty such prefixes spent 85% of its instructions comparing a child with itself (callgrind on a profiling build, `<Schema as Ord>::cmp`).
- **An unfolding builds one copy of a body a level** (`Schema::unfolded`): a reference's unfolding is built once per definition, unfoldings left and polarity, and every reference holds that handle, so a body naming its definition `m` times unfolds twice into two copies rather than `m` of `m`.
- **A record opened pays one test.** `clauses_over` answers a node with no clauses in its caller and reads a clause list out of line (`clauses_over_a_list` in `ir.rs`): with the whole function a call, opening the core workload's records reads 1.9% dearer.
- **Lists are assembled in per-thread buffers** and moved into the node, and the lists every record shares -- an open record's catch-all, a closed one's empty one -- are allocated once for the process.

### The build

The release profile in `Cargo.toml` links with fat LTO into one codegen unit and wraps rather than checks integer overflow, which the dev and test profiles trap; `[profile.profiling]` is the same build with its symbols kept, for a profiler. The published CPython wheels for glibc Linux, macOS and Windows x64 are profile-guided, trained by `scripts/pgo_workload.py`, which `pyproject.toml` names as `pgo-command`, and the musllinux, Windows arm64 and PyPy wheels are plain release builds (`.github/workflows/release.yml` says why); what that buys, and on which shapes it costs, is [measured above](<#baseline-matrix>). A path the training workload never enters is laid out by chance, so the workload reads lists of scalars, of literals, of one class, of tuples, of named tuples, of dataclasses and of records, records open and closed, the closed ones built two hundred times each so the frontend holds counts of its own, a deeply nested list, scalars through `is_valid` and through `x in v`, the explaining walk, a JSON array of records and a recursive JSON document, a set, a named tuple read against a tuple schema, and relations at both of their levels. `TRAINED` in the workload names, for each shape a gate measures, the calls that take its reading, and `UNTRAINED` names the shapes none does with what each reads: a value walked against a recursive schema and a union read over a JSON array among them.

### Measured and not taken

Each of these reads as an obvious gain and measures as a loss on a shape the gate holds, under `scripts/perf_gate.py --against` unless it says otherwise:

- **Resolving a record's keys by iterating the dict**, rather than probing each declared key: 47.9% dearer, as above.
- **Reserving a record's field vector from the dict's length** while building it: the build shape reads 9% dearer, because one large request leaves glibc's fastbins, where growing from empty is served from bins already warm.
- **An unstable sort for the canonical orders**: 7% dearer on the build shape, since its swaps over a record's fields cost more than the stable sort's scratch buffer.
- **A memo over every goal of a query**: up to 18% dearer on the queries whose goals do not repeat, which is most of them; the memo kept is one entry, in the one loop where a goal repeats.
- **Comparing an order bound as a native integer, a value at a time**: 28% dearer on `--binding-refined`, since reading a Python integer out costs more than the rich comparison it would replace. Read once per value and once per bound as a machine word, it is still 4.6% dearer on CPython 3.14, and an `int` past the word raises on every read, nearly four times the cost. A `float`, whose value is a field and whose read cannot raise, is taken ([Walking a Python value](<#walking-a-python-value>)), and a list reads its bounds once and stops reading words at the first that raises, which is what makes [a list's range](<#sequences-and-sets>) a gain.
- **A JSON string cache of keys only, or none**: jiter's default caches every string it parses, and parsing alone on CPython 3.14, a 1.5 MiB document of ninety thousand distinct strings reads 18% faster caching keys only and 28% faster caching none. The others read slower: 1.8 MiB of records 7.5% and 9.4%, 1.1 MiB of strings drawn from fifty twice the time, sixty thousand one-key objects 4.6% and 29%.
- **Answering a union of scalars by the element's exact type**, from a table of the builtin types the union's kinds admit built once per list: a list of a thousand `int | str` costs 25% fewer instructions in the PGO wheel, but an eight-element list costs 26% more for the table, a homogeneous tuple of `int | None` 26% more, and `--binding-nullable` reads 6.8% dearer on CPython 3.12, where the member test the table replaces is already inlined.
- **Remembering a string's length across a refinement's bounds**: `Annotated[str, MinLen(1), MaxLen(64)]` reads the length once for each bound, and a length kept for the second costs a list of a hundred such strings 11.6 to 15.5% fewer instructions on CPython 3.14. Kept as a parameter of the bound check, reset where the walk runs code, or keyed by the value's address, it costs `--binding-refined` 2.0 to 4.3% more; read in one pass over the run of length bounds, it costs that shape nothing and the list of strings 12% more. A list folds its bounds into one range instead, read once for the list ([Sequences and sets](<#sequences-and-sets>)).
- **A two-word walk context**: one reference to everything a walk reads, beside its mode, travels in two registers and is never copied, but a read through a frame takes one load more: `--binding-boundary` reads 8.7% dearer, `--binding-refined` 4.1% and `--binding-subclass` 3.4%, where the JSON shapes read about 1% cheaper.
- **A replacement global allocator**: up to 28% cheaper on the JSON shapes and 12% dearer on the call boundary, past the gate's ceiling, for a C dependency on every wheel target.
- **A snapshot of a list on CPython 3.14**: 1.65 ns an element against 1.28 in place, timed, because that interpreter makes the reference counts cheap.
- **Aligning code to 64 bytes**: a function starts on a 16-byte boundary, so a change anywhere in the library can move it 16 bytes across the processor's 64-byte fetch lines. A list of a thousand refined integers read 2% more cycles on CPython 3.14 in one build than in another at an equal count, nearly all of it frontend stalls: its function's code is identical and starts 16 bytes later in its line. Loop heads aligned to 64 bytes leave it 1.7% dearer, and functions aligned to 64 bytes 2.0%, for a library 1.5% larger; every other shape moves about 1% either way under either, inside its own shape's spread. Read with `perf_inspect.py cycles`, thirty rounds.
- **Reading a meet's complemented member as a difference while lowering**: the relations of the JSON Schema containment suite read 0.6% fewer instructions, since the complement a meet stops building is mostly built again by the record that holds it, for five more lines at the build's busiest match.
- **Forcing the emptiness entry into its callers**: `#[inline]` on `verdict_rec` or `empty_and_region` changes no count, and `#[inline(always)]` moves the call one frame down and reads the relation matrix 0.06% dearer.
- **A list of dataclasses reading its record's names once**, rather than once an element: `--binding-object-walk` reads 0.67% cheaper, and drawn apart from the record's check, what is left of that check is inlined into the walk's every node, which reads a list nested twenty-five deep 8% to 12% dearer in cycles at one count.
- **A tagged union's test at the first branch walked**, rather than before the scan: a union of scalars reads 0.37% cheaper, and a recursive schema 0.83% dearer and a union of literals 0.18% dearer, for the same two tests.
- **A definition's tree plan asked by its bit in a `u128`**: the shift of two words is thirteen instructions at every reference, which a recursive schema with no tree of scalars pays, and `--binding-memo` read 2.1% dearer on the build without a profile. The arm asks whether the index holds a plan at all.
- **A leaf evaluated node by node at each element**: `number`, `(int | float >=   -inf) & ~bool`, walked as its meet, union and complement over a `float` costs about 240 instructions where its specialization to `float` is one comparison, and the JSON values over two hundred records read 18.5% dearer than with the tree's own bounds. The plan specializes the leaf to each exact type at build.
- **A parsed value read as a tree of scalars**: each value's tag is its exact type, and the JSON values over a document of two hundred records cost 35% fewer instructions to check, the parse included. Taking it means the reference's arm stops asking whether its value is a Python one, and the profiled CPython 3.15 wheel then laid `member` out so that a list nested twenty-five deep, which enters no reference, read 1.8% more instructions and 12% more cycles, thirty rounds of thirty, its frontend stalls three times as many.
- **A reference's arm asking past one word whether a tree is held**: the plans of leaves and trees share one word of the index, and asking for the trees behind it is a load more in an arm inlined into every walk, which the profiled wheel read three instructions a level dearer on a list nested twenty-five deep, a walk that enters no reference. The arm asks the word alone, and a validator holding leaves and no tree pays a call that declines.
- **The tree plans held in two words of the validator's index**: its fields fill 248 bytes under an alignment of 16, so a second word grows it to 272, and every frame holding a validator is laid out anew: `--binding-boundary` read 2.9% dearer on the build without a profile, though it walks no reference. One word fits the alignment's padding.
- **Leaving a tree of scalars out of the memo**: a value meets at most one of a tree's members, so a walk of it reads each value below once, and a JSON Schema translation's meets of `list[J]` and `dict[str, J]` arm the memo for the tree alone. Not remembered, the tree is read whole again at every level of such meets, where kept, each container is read once: on the profiled CPython 3.15 wheel valgebra-jsonschema's record array checked in 43.6 us where the kept walk took 79, but a chain of sixty objects against a recursive `$ref` took 56.7 us where it took 26, a chain of forty arrays of objects 124 where it took 38.5, and its `$ref` tree eight deep 220 where it took 196. A kept walk reads the tree's scalars by type instead ([a kept walk](<#walking-a-python-value>)).
- **Reading a record's leaf field by its type in the record's field test**: a field JSON Schema's `integer` translates to, a meet, is walked where `scalar_member` answers a bare kind. Read there by its leaf, valgebra-jsonschema's record array counts 4% fewer instructions on the profiled CPython 3.15 wheel, but the field test is inlined into every record's field loop and every default clause's, and the arm moved them all though no gate shape reaches it: a record walked by interned keys read 2.8% dearer, a mapping of lists 11.5%, and the other record shapes 1.2% to 1.9%.
- **Reading a record's leaf field at the meet's arm of the walk**: the same field read by its plan where `member` dispatches a meet, behind the index's one word, as the reference's arm asks it. valgebra-jsonschema's `$ref` tree of 511 nodes counts 18% fewer instructions and its record array 18%, but the arm lays out `member`, which every shape crosses: on the profiled CPython 3.15 wheel the list nested twenty-five deep read 6.73% more instructions, a record 1.53%, a dataclass 1.67%, a literal 1.62%.
- **Training the loop over a leaf holding a tree**: a line in `scripts/pgo_workload.py` reading a list of `(~NUMBER | Ge(0)) & J` takes the `if/then` array from 165,119 instructions a call to 110,191, but the list nested twenty-five deep reads 2.36% more, at a hundred rounds as at five hundred: past the profiled gate's ceiling. The loop runs untrained.

## Regression gate

The wall-clock numbers above are for humans reading results; they are too noisy on shared CI runners to gate a merge. The merge gate is instead a deterministic instruction count: `scripts/perf_gate.py --against` runs each fixed workload under cachegrind at the change and at its base, in one job with one toolchain, and fails on a rise past the band it allows a change. The count is identical across runs of a given build, so the gate does not flake, and measuring both sides in one job cancels what another machine or another toolchain would add, while an algorithmic regression is far larger than the band. The counts in `scripts/perf_budget.json` are a record of one environment rather than a gate, since the same commit re-measures several percent away on another machine: the gate reads one only where the base has no count to compare with -- a shape the base does not carry, or a re-recorded workload the base cannot build -- and a step the file records excuses the one comparison that crosses it (`docs/dev/tooling-ci.md`).

The gate holds one workload per surface, because a gate only catches what it exercises. `crates/valgebra-core/examples/` holds the pure-Rust ones: the schema transformations (`perf_workload`), and the decision procedures, one workload for each path a relation takes, which `MODES` in `scripts/perf_gate.py` names -- a proof, a refutation, a repeated goal, a shape only the structural readings decide, and one corpus asked of the rules and of the sets each walk a different path, and a workload that asks only one of them measures only that one. The binding's shapes are `BindingShape` in `crates/valgebra-py/src/workload.rs`, run by `crates/valgebra-py/examples/binding_workload.rs`, and `BINDING_SHAPES` in `scripts/perf_gate.py` names every one the gate measures: the membership walk over a live value, the call boundary, the record walks closed, open and over interned keys, the builds, the JSON document and the explaining walk among them. The walk is the shipped hot path neither pure-Rust workload reaches, and construction and the open record are each a cost no other shape's count carries. A surface with no shape of its own can move by percents a release at a time with every gate green.

Each binding shape embeds CPython, whose startup is not a fixed count, so the gate measures the difference between two iteration counts. **What a shape's loop holds is part of what its count means**, and is read before the number is: a build shape that assembles its fifty fields inside the loop spends most of its count on the harness naming them and none of it on the annotation walk, which is the half a build gate exists to measure.

One thing an embedded interpreter brings with it is its **string hash seed**, drawn per process; a shape that probes a dict of string keys executes a different number of instructions under every seed, and on the difference of two counts that is a few percent -- the size of the ceiling. The gate fixes the seed where every measurement passes through, so a reading is of the code and not of the interpreter's draw. A number in this page is a wall-clock figure for a human; the counts belong to the budget file and are not repeated here.

The end-to-end wall-clock suites run on the same CI lane with timing disabled, as a smoke test that they keep working.

The headline claim — that valgebra's check is as fast as pydantic's — is gated too, by `scripts/compare_gate.py`. For each shape in a matrix it measures the *ratio* of per-call time (valgebra over pydantic's strict `TypeAdapter.validate_python`, called through a lambda as a caller holds it), taking the minimum over many repeats, and holds it under the ceiling `scripts/perf_compare.json` states for that shape -- what the project claims, not what it measured -- and, where the file carries a ratio recorded in the same environment, within that shape's tolerance of it. The lambda and the adapter are a Python frame a direct pydantic-core `SchemaValidator` call does not pay, and on a scalar that frame is most of pydantic's time: against `SchemaValidator` the scalar shape reads about 1.0, several times what its ceiling against the adapter allows (`ceilings` in `scripts/perf_compare.json`), on one box with a release build and no profile. So the ratio is to what a caller reaches, not to pydantic-core. A ratio cancels the runner's absolute speed: if the machine is slow, both libraries are slow in proportion, so the comparison survives the shared-runner noise an absolute budget cannot. A shape fails the merge gate when valgebra's ratio crosses its ceiling, or drifts past its recorded ratio where one is armed — a competitive regression, whether from valgebra slowing down or ceding ground.

Re-record the counts after an intentional change with:

```
uv run --no-sync python scripts/perf_gate.py --update  # the core count; --decision, --binding-record, ... for the others
uv run --no-sync --group bench python scripts/compare_gate.py --update  # one run's ratios, a reading for a window
uv run --no-sync python scripts/compare_gate.py --record-window WINDOW.json  # arms the ratchet from the lane's window
```

## Reading one build against another

The gates above each hold one reading of one build against its base. `scripts/perf_inspect.py` reads any build against any other -- a release on PyPI, a wheel, or a revision built as the release builds it -- over the shapes `scripts/perf_shapes.py` holds, on the interpreter it is given, and says which of three readings each figure is:

| reading | what it counts | what it cannot see |
| --- | --- | --- |
| `count` | instructions per call under cachegrind, as the difference of two runs, in the instruction gate's environment | a cache, the branch predictor, the alignment of a loop: time |
| `cycles` | the processor's own cycles, instructions, branch mispredicts and frontend stalls per call, through `perf_event_open`, the environments interleaved | a difference under the spread between two readings of one build, and any machine whose kernel gives no counter |
| `symbols` | the functions, or with line tables the source lines, that spend the instructions one build spends over the other; with `--per N`, the instructions run `N` times a call, disassembled | time, as `count` cannot |

```
uv run --no-sync python scripts/perf_inspect.py env last --python "$(uv python find --managed-python 3.15)" --release 0.0.19
uv run --no-sync python scripts/perf_inspect.py env head --python "$(uv python find --managed-python 3.15)" --build
uv run --no-sync python scripts/perf_inspect.py count last head
uv run --no-sync python scripts/perf_inspect.py cycles last head --shapes deep records
uv run --no-sync python scripts/perf_inspect.py symbols last head --shape deep --per 25
```

`env` makes an environment under `target/perf-inspect/` holding the standard library and one valgebra; `--build` builds the checkout, or the revision it names, with the training's hash seed fixed, from a directory whose path is one length whatever the tree, so two builds differ in their sources and nothing else. Every reading is against the first environment named. `count` exits 1 where `--tolerance` is given and a shape rose past it; every reading exits 2 where it cannot be taken. It needs valgrind, `uv` for `--release`, and for `--build` the `llvm-tools` component the PGO build needs.

**Read a change against the last release on every interpreter the wheels ship.** Each interpreter's wheel is trained and laid out on its own, so a reading on one says nothing about another: one release read a list nested twenty-five deep 3.1% dearer than the release before it on 3.12 and 0.2% on 3.14, and a hundred-entry `dict[str, int]` 5.4% dearer on 3.14t and 2% to 3% cheaper on every build with a global lock. One `env` per interpreter and side, and one `count` per pair, is the reading; a survey of one interpreter is a reading of that one.

**Decide on the count, and confirm in cycles.** On a build with the GIL a count is deterministic: two builds of one source and one toolchain read it to the instruction between environments whose names are one length, so a difference is the code's -- on a shape that allocates, where it reads the same at a second size of the environment, as the next paragraph says. On a free-threaded build, a shape of a few thousand instructions is not exact: two counts of one pair on 3.15t read `literal` -0.03% and -13.5%, and `scalar` +6.3% and +8.7%, where `validate` read +1.9% both times. Count such a cell twice, and read one that does not repeat as nothing shown. A count does not predict time on every shape: that nested list read 0.2% more instructions in one release than in the one before it, and 4% more cycles. `cycles` reads what the count cannot and carries the machine's noise, so it starts each round at the next environment, prints the median of the rounds, and beside it the rounds in which each environment read slower: a cell inside the spread of the same build read twice has shown nothing. On the machine above that spread is about 2%, 4% on a shape of a few hundred cycles, and it is a shape's own: two environments of one build read `list[int | str]` 14% apart, at every round of two runs, where `list[int]` read 0.6% apart. So the control is the base in a second environment, read in the same run, and each cell is weighed against its own shape's control.

**A shape that allocates is counted at a second size.** It reads the heap its loop starts from, and everything run before the loop leaves that heap, the environment included: one release in two environments named a character apart read `explain_record` 3.1% apart and `json_records` 0.7%, and to the instruction at one length. Two builds may move together as the environment grows, or apart. Two that build a validator to the instruction alike differed by the same count, within 0.02%, at every size up to 8,200 bytes larger on 3.11, 3.12, 3.14 and 3.15, where each alone spread up to 3.7%; the builds of two releases read `json_deep` anywhere from 1.5% cheaper to 8.0% dearer by the environment's size alone. `count --pad BYTES` adds that many bytes to every run's environment, so a shape that allocates and reads dearer is counted again at two sizes, `--pad 600` and `--pad 1100`: a difference that is the code's reads the same at each. Trimming the heap before the loop, as the binding gate does, is not the remedy here: it took `explain_record`'s 3.1% to 0.02% and moved `json_deep`'s from 0.3% to 0.7%.

**Read a change against its base built the same way.** A base `--build` made differs from the change in its sources alone; a release also differs in the container and the path it was built in, which the layout follows, and in the binary a shape that allocates hands the C library's allocator: on 3.11 PyPI's 0.0.19 read `explain_record` 0.84% below a build here of its own commit, 167 instructions a call in `_int_malloc`, and 0.39% above it with the environment 1,100 bytes larger. So a change is read against its base's revision built here, and charged in cycles only that way. A release's own wheel is read by count, for what it ships, and once published in cycles against the last release's, for what a user meets: step 9 of `docs/dev/releasing.md` names a move there and charges it to no change.

**`symbols` names where, not why.** A release wheel is stripped, so it names the extension's functions only between builds `--build` made; against a release it names the C library's alone, which is where an allocator's luck shows -- a `realloc` that copies, read as `memcpy`. A function inlined into another reads as its caller, which is why `--per` reads past functions to the instructions themselves. `--lines` adds line tables and leaves the code as it is -- a list nested twenty-five deep counts the same with them and without -- while the length of the path a tree is built from moves it: the same tree built from a path two characters longer read that list 1% cheaper. `--build` unpacks every tree at one length for that reason. `tests/test_perf_inspect.py` holds the readers of both output formats to hand-written files.
