# What a validator cannot do

Every entry here is a *deliberate* boundary rather than an unfinished feature. They come from two places: what a runtime check can observe at all, and what this library decided not to be. Knowing which is which tells you whether to wait for it, work around it, or use another tool — so each says which it is.

The neighboring pages cover two nearby questions: [resource limits](<https://ppigazzini.github.io/valgebra/guides/limits/index.md>) is what a *value* cannot make the validator do, and the [decidability boundary](<https://ppigazzini.github.io/valgebra/explanation/decidability/index.md>) is what the comparison operators cannot yet prove. This page is about the shape of the product.

## It does not convert

A validator answers whether the object you already hold is a member of a set. It never copies, coerces, or returns a different value: `"1"` is not an `int`, a missing key is not filled from a default, and no field is renamed on the way through. `ensure` returns its argument — the same object, so `is` holds.

This is the product decision the rest of the library rests on. A tool that converts is answering a different question, and there are good ones; reach for one when the input is a wire format you need to *become* a domain object.

```
from valgebra import Validator

numbers = Validator(int)
value = 1
assert numbers.ensure(value) is value  # the same object, not a copy
assert not numbers.is_valid("1")  # a string that looks like one is not one
```

## It does not read the future of a value

The check is a decision about a value at one moment. A value that is mutated afterwards is not re-checked, and nothing is frozen: validating a list says the list's elements belonged to the set when they were read.

An observable consequence: a container whose size changes while the walk is reading it is reported rather than silently half-checked, because the alternative is an answer about a value that never existed. A change that keeps the size is not seen, and the answer is about what the walk read ([error model](<https://ppigazzini.github.io/valgebra/guides/error-model/index.md>)).

## It cannot look inside a callable

`Callable[[int], str]` names a function's domain and return, and neither is observable at runtime: no check can ask an arbitrary function what it accepts without calling it, and calling it is not a membership test. A callable schema is therefore an `isinstance` check for *being* callable, and the argument types are not checked at all.

```
from collections.abc import Callable

from valgebra import Validator

callables = Validator(Callable[[int], str])
assert callables.is_valid(len)  # any callable belongs
assert not callables.is_valid(3)
```

A `Protocol`'s method is read the same way: the value's attribute is callable, and its parameters and return are not asked.

## It reads values, not declarations

A relation is inclusion between sets of values; a static checker's assignability is a relation between declarations, and the two part where a checker reasons about what a declaration permits. A mutable member is invariant to a checker, so a class declaring `count: bool` is not assignable to a protocol declaring `count: int`. Over values every `bool` is an `int`, so the class's set is inside the protocol's, and `relation_to` says `"subset"`. A `TypedDict` declaring `x: bool` is below one declaring `x: int` for the same reason.

```
from dataclasses import dataclass
from typing import Protocol

from valgebra import Validator


class Counted(Protocol):
    count: int


@dataclass
class Flag:
    count: bool


assert Validator(Flag).relation_to(Validator(Counted)) == "subset"
```

The same reading decides what a class's declarations cannot. An instance of a plain class annotated `x: int` can be given `x = "s"`, so the class is not below a protocol of `x`, whatever a checker says about it. And a special method set on the instance satisfies a protocol's member as any attribute does, though `len()` and the other operators read it from the type.

A class is its instances at run time, which is not always what a stub says. The stubs declare that `open()` returns a `typing.TextIO`, and no stream derives from that class: `isinstance(io.StringIO(), typing.TextIO)` is `False`, so `Validator(typing.TextIO)` admits no stream either. The class the streams do derive from is `io.TextIOBase`, and that is the one to write:

```
import io
import typing

from valgebra import Validator

assert not Validator(typing.TextIO).is_valid(io.StringIO())
assert Validator(io.TextIOBase).is_valid(io.StringIO())
```

## It cannot see a generic's arguments on a value

Python erases them. A `list` at runtime is a list of whatever it holds, so `list[int]` is checked by reading the elements — which is why it works — while `Sequence[int]` and `Mapping[str, int]` are refused: those name *protocols* whose instances need not be enumerable without consuming them, and a check that consumed an iterator would change the value it was asked about.

There is no variance and no type variable, for the same reason: a `TypeVar` is a statement about a *relationship between* uses in a program, and a runtime check sees one value.

## A predicate is a black box

A `Predicate` refinement runs your callable. That makes it as expressive as Python — and opaque to the algebra: the complement of a predicate is not a set the library can reason about, two predicates are not compared, and a schema carrying one is answered conservatively by every relation ([decidability](<https://ppigazzini.github.io/valgebra/explanation/decidability/index.md>)). Predicates are the escape hatch, and using one is choosing expressiveness over decidability.

The same holds of a class whose metaclass answers `isinstance` by running code: what it admits is not a set that stands still, so the complement laws are not applied to it. Telling such a class from a plain one needs the class object, which construction does not consult, so construction declines the two folds for every class (`denotes_a_set_within` in `crates/valgebra-core/src/oracle.rs`): a plain class's meet with its complement keeps its spelling, and `is_empty` decides it empty.

That is why `A & ~A` is not folded to `nothing` when `A` carries a predicate or a class, and `A | ~A` not to the top. The laws are about sets — a value is in `A` or it is not, once — and the two occurrences of `A` there are two calls. A predicate that does not answer from the value alone answers them differently, and a value then really is admitted by the meet. The fold would be a claim the schema contradicts, so it is refused rather than approximated; a `Regex` folds, because a pattern is a function of the string.

## Your code runs inside the check, and may call back in

A predicate, an `__eq__` behind a `Literal`, an `isinstance` hook, a `keys()` — membership runs your code at almost every entry of a container, and while it runs the check is on the stack. That code may call valgebra again. It may build a schema, ask a decision, or re-enter the very validator that called it: the walk keeps its recursion guard in a per-call local, so a nested check is an ordinary one and does not disturb the outer.

```
from collections.abc import Iterable
from typing import Annotated

import annotated_types as at

from valgebra import Validator

rows = Validator({"id": int})


def every_row(value: Iterable[object]) -> bool:
    return all(rows.is_valid(row) for row in value)


page = Validator(Annotated[list, at.Predicate(every_row)])
assert page.is_valid([{"id": 1}, {"id": 2}])
assert not page.is_valid([{"id": 1}, {"id": "two"}])
```

What bounds it is Python's own recursion limit and the native stack, not a valgebra bound: the walk's depth guard is per call, so each re-entry starts a fresh walk on top of the frames the last one holds. On CPython a predicate that re-enters without a base case raises `RecursionError`, on any thread: 3.14 and later raise it at the Python frame between two calls, where the thread's stack runs short, and before 3.14 the walk reads the thread's stack before it calls a predicate and raises it there, with 32 KiB left. Before 3.14 the question is the predicate's alone: an `__eq__` or an `isinstance` hook that re-enters is not asked. On musl neither check stands: the walk does not read the stack, whose reading for the main thread is the stack mapped so far, and CPython 3.15.2's own check ends in a segmentation fault on a thread of 128 KiB. On PyPy the process ends in PyPy's own stack check, inside `cpyext`, with no nesting between the calls. No check reads the walk between two calls, though, so where each re-entry walks levels of nesting near the end of the stack, the walk's own frames can run past it and the process ends: CPython 3.15 does where a predicate re-enters under sixty levels of lists on a 1 MiB thread. Give a re-entering predicate a base case, and run it on a thread of 1 MiB or more.

A fatal signal is **not** turned into a verdict: a base exception that is not an ordinary `Exception` (`KeyboardInterrupt`, `SystemExit`, `GeneratorExit`), and `MemoryError` and `RecursionError`, propagate, because a check that swallowed one would make the process unstoppable from inside a loop or hide the interpreter running out of a resource. The set is the one the walk page (`docs/dev/walk.md`) owns and [the error model](<https://ppigazzini.github.io/valgebra/guides/error-model/index.md>) lists. Everything else a predicate raises is reported as `predicate_error` rather than as a rejected value ([refinements](<https://ppigazzini.github.io/valgebra/guides/refinements/index.md>)), so a bug in your callable is not mistaken for data that failed.

The one thing your code must not do is **resize the container being checked**. That is not refused — it is reported: the walk reads every container against a count taken once, and a count that moved makes the reading cover no state the value was ever in, so the answer is `mutated_during_validation` and a non-member ([error model](<https://ppigazzini.github.io/valgebra/guides/error-model/index.md>)). It applies equally to another thread on a free-threaded interpreter, which is the case that cannot be written out of a program by discipline.

## It reads an array through what the array exposes

A numpy array is an instance of a class, so `numpy.ndarray` builds as that class and reads no element. A scalar belongs where its class derives: `np.float64` subclasses `float` and is a `float`, to the relations as to the walk, and `np.float32`, `np.int64` and `np.bool_` subclass no builtin and are none of `float`, `int` and `bool`:

```
import numpy as np

from valgebra import Validator

assert Validator(np.ndarray).is_valid(np.zeros(3))
assert not Validator(list[float]).is_valid(np.zeros(3))

assert Validator(float).is_valid(np.float64(1.0))
assert Validator(np.float64).is_subtype_of(float)
assert not Validator(float).is_valid(np.float32(1.0))
assert not Validator(int).is_valid(np.int64(1))
assert not Validator(bool).is_valid(np.bool_(True))
```

A bound over `float` asks the value, so `np.float64` answers it by numpy's comparison, which converts an `int` to a float first: the relations read a bound past `2**53` as `float` does, and [the soundness page](<https://ppigazzini.github.io/valgebra/explanation/soundness/index.md#what-this-argument-assumes>) names the difference.

numpy's own generic reads what it names. `np.ndarray[S, np.dtype[T]]` denotes the instances of `np.ndarray` whose `shape` is in `S` and whose elements are `T`'s, read by the `kind` and the width of its dtype. So a byte order is storage and reads alike, and `np.int64` and `np.longlong` are one element where the platform makes them one width. The width is read where the validator is built, so `np.long`, 8 bytes on 64-bit Linux and 4 on 64-bit Windows, is a different set on each, and an array that crosses keeps the width it has: write `np.int32` where arrays cross platforms. `Any` in either place asks nothing, a shape is a tuple or a union of tuples, and an abstract scalar type such as `np.floating` is refused, since `np.dtype` makes no dtype of it. The relations decide what it says:

```
from typing import Literal

import numpy as np
import numpy.typing as npt

from valgebra import Validator, intersection

rows_of_three = Validator(np.ndarray[tuple[int, Literal[3]], np.dtype[np.float64]])
assert rows_of_three.is_valid(np.zeros((4, 3)))
assert rows_of_three.is_valid(np.zeros((4, 3), dtype=">f8"))  # whichever its byte order
assert not rows_of_three.is_valid(np.zeros((4, 4)))
assert not rows_of_three.is_valid(np.zeros((4, 3), dtype="float32"))

doubles = Validator(npt.NDArray[np.float64])
assert doubles.is_valid(np.zeros(3))
assert doubles.is_valid(np.zeros((2, 2)))
assert rows_of_three.relation_to(doubles) == "subset"
assert rows_of_three.relation_to(np.ndarray) == "subset"
assert intersection(doubles, npt.NDArray[np.float32]).is_empty()

# A refutation names a value, and no decider builds an array.
assert doubles.relation_to(rows_of_three) == "undecided"
```

A set that form does not name, floating elements of any width, is a `Protocol` over the same attributes, met with the class:

```
from typing import Literal, Protocol

import numpy as np

from valgebra import instance_of, intersection


class FloatKind(Protocol):
    kind: Literal["f"]


class FloatElements(Protocol):
    dtype: FloatKind


floats = intersection(instance_of(np.ndarray), FloatElements)
assert floats.is_valid(np.zeros(3, dtype=">f8"))
assert floats.is_valid(np.zeros(3, dtype="float32"))
assert not floats.is_valid(np.zeros(3, dtype="int64"))
```

**The elements are not read.** An element is no attribute, so a set over them is a predicate: exact on membership, and every relation that looks inside it declines.

**An order bound on an array holds one-element arrays alone.** `Annotated[np.ndarray, Ge(0)]` denotes the arrays for which `x >= 0` holds. For an array that is an array, its truth raises unless it holds one element, and a comparison that raises does not hold. So the bound refuses `np.zeros(3)`, every element of which is `>= 0`. No value is misread, and the set is not what the spelling suggests. Write the predicate:

```
from typing import Annotated

import annotated_types as at
import numpy as np

from valgebra import Validator

bounded = Validator(Annotated[np.ndarray, at.Ge(0)])
assert bounded.is_valid(np.zeros(1))
assert not bounded.is_valid(np.zeros(3))

non_negative = Validator(
    Annotated[np.ndarray, at.Predicate(lambda x: bool((x >= 0).all()))]
)
assert non_negative.is_valid(np.zeros(3))
assert not non_negative.is_valid(np.array([-1.0, 2.0]))
assert non_negative.relation_to(np.ndarray) == "subset"
assert Validator(np.ndarray).relation_to(non_negative) == "undecided"
```

**Another library's array is read the same way.** The spelling asks for attributes, so it holds of whatever has them, met with that library's class. No other library's array has a generic form to read:

| Array | `shape` | Its elements |
| --- | --- | --- |
| `jax.Array`, met as `instance_of(jax.Array)` | a `tuple` | `dtype` is numpy's, so `kind` reads as above |
| `torch.Tensor`, met as `instance_of(torch.Tensor)` | `torch.Size`, a `tuple` subclass, which a `tuple` schema reads | `dtype` has no `kind`: `is_floating_point`, `is_complex` and `is_signed` are its attributes |

jaxtyping's `Float[Array, "n 3"]` builds as what it is, a class with an `isinstance` hook: membership reads its dtype and shape exactly, and every relation is `undecided`. The Array API's `isdtype` is a function, so a set over it is a predicate, and a `torch.Tensor` has no `__array_namespace__` to ask. These were read on JAX 0.12 and PyTorch 2.15, and no lane here installs either.

**Under `jax.jit` the attributes still read and the elements do not.** A traced value is a tracer with a `shape` and a `dtype`, so a record reads it as it reads an array. A predicate over its elements raises what a tracer's truth raises, which is `predicate_error`, so `is_valid` answers `False` inside `jit` for an array it admits outside. Keep what a traced function checks to the attributes.

## It does not generate, infer, or export

- **No schema inference from values or code.** A schema is written, not guessed.
- **No serialization.** Nothing here turns a value into JSON or back; the JSON path *validates during parsing* ([JSON input](<https://ppigazzini.github.io/valgebra/guides/json/index.md>)) and produces the same accept/reject decision as the object path, not a serializer.
- **No JSON Schema import or export.** The two describe different value universes — JSON has no `bytes`, no `tuple`, and no class identity — so a translation would be lossy in both directions rather than merely absent.
- **No witness.** A refuted relation names no value: `relation_to` answers `"not_subset"`, and no call builds a member of a schema or of a difference. Building one is a constructor per kind -- a string from a pattern, a dict from a record -- with none for a class instance or a predicate, so it would be partial by nature. A value to show is found by sampling and checked with `is_valid`, whose membership is exact, as [inspection](<https://ppigazzini.github.io/valgebra/guides/inspection/index.md#what-this-cannot-see>) does it.
- **No static checking.** valgebra runs; a type checker does not run it. The two are complementary, and the [foundations](<https://ppigazzini.github.io/valgebra/explanation/foundations/index.md>) page says where their models agree and where they part. What a checker reads from a validator, and the spellings it refuses, are on [static checkers](<https://ppigazzini.github.io/valgebra/guides/static-checking/index.md>).

## One operator, and it is the one typing already uses

`a | b` builds a union, because `|` is what Python's own type syntax uses for one — `int | str` is a union before valgebra sees it, and `__ror__` is what makes `None | validator` work. There is no `&` and no `~`.

That is the ship-versus-recipe rule rather than an oversight: `intersection` and `complement` are functions that already exist and say what they do, and an operator spelling for them would be a second way to write the same thing whose only argument is that it is shorter. `|` is not a second way to write `union` — it is the way the language spells it.

```
from valgebra import Validator, complement, intersection

assert (Validator(int) | str).is_equivalent(int | str)
assert not hasattr(Validator(int), "__and__")
assert intersection(int, str).is_empty()
assert complement(int).is_valid("x")
```

## A validator does not pickle

It holds the classes an `isinstance` atom names and the callables a predicate runs, so pickling one would have to pickle those — a different question with a different answer per object. Send the **schema** instead and rebuild on the other side: compiling is cheap, and gated as such — building a fifty-field record from its Python spelling is one of the shapes `scripts/perf_gate.py --binding-build` holds to an instruction count, and `scripts/perf_budget.json` owns the figure. `repr(validator)` gives an expression that rebuilds the schema, except for the forms [the API reference](<https://ppigazzini.github.io/valgebra/reference/api/index.md#operators-on-a-validator>) lists, and the refusal says so. A **required record key whose name ends in `?`**, which the dict literal cannot spell because every trailing `?` there marks the key optional ([schema language](<https://ppigazzini.github.io/valgebra/guides/schema-language/index.md#a-key-name-that-ends-in-a-question-mark>)), prints marked, `<required: 'a?'>`, and its `repr` is a syntax error where it is read. One form rebuilds quietly: a **class met with a declaration it did not make**, which prints as the class's name and rebuilds as the class with its own. A schema carrying any of them is a schema to send as itself rather than as its `repr`.

```
import pickle

from valgebra import Validator

raised = False
try:
    pickle.dumps(Validator(int))
except TypeError as error:
    raised = True
    assert "cannot be pickled" in str(error)
assert raised
```

A `ValidationError` **does** pickle, because a failure has to be able to cross a process boundary back to whatever started the work.

## It holds what its schema names, and lets go of it

A schema names classes, enum members and callables, and a validator keeps a reference to each: the walk reads them, so they must not be collected underneath it. That makes the natural spelling a reference cycle — a class that keeps its own validator holds the validator, and the validator holds the class — and the validator takes part in the cycle collector so the pair is freed like any other.

```
import gc
import sys
import weakref

from valgebra import Validator


class Model:
    a: int


Model.validator = Validator(Model)
watch = weakref.ref(Model)
del Model
gc.collect()
if sys.implementation.name == "cpython":
    assert watch() is None
```

The pair is freed on CPython. PyPy keeps alive every class an extension module is shown, valgebra's or any other's, so there the class outlives its last reference whether a validator holds it or not; [PyPy](<https://ppigazzini.github.io/valgebra/get-started/installation/index.md#pypy>) on the installation page says what that costs a long-running process.

A validator can also be weakly referenced, so a registry keyed by schema can be a `WeakValueDictionary` and let its entries go.

## It loads in the main interpreter of a process, once

A schema's forms are read by identity: `Annotated`, `Literal`, `Any`, a dataclass's fields and the markers of `annotated_types` are the objects the first build found in `typing` and the rest, kept for the life of the process. A subinterpreter holds its own copies of those modules, whose forms the kept ones are not, so a schema it built would mean something else: a pattern dropped, `Any` refusing every value. So `import valgebra` raises `ImportError` in any interpreter but the main one, whichever imports first, and in an interpreter an embedder starts again after `Py_FinalizeEx`, which would read what the first one freed. Importing it again in the interpreter that loaded it -- a reload, a cleared `sys.modules` -- works.

Under `mod_wsgi`, whose application groups are subinterpreters by default, run the application in the main interpreter with `WSGIApplicationGroup %{GLOBAL}`, as other extension modules ask. An isolated subinterpreter, such as one from `concurrent.interpreters`, refuses the module on its own: it declares no support for one.

## It does not enforce ordering between separate checks

Two validators are two questions. A constraint that relates *two* values — this field is greater than that one, this id exists in that table — is not a set of values in the algebra's sense unless the relation is written inside one schema, where a predicate can see both. Cross-value invariants belong in the code that holds both values.

## What follows from all of this

The boundaries are what buys the guarantees. Because nothing converts, an accept says something about the object you hold rather than about a copy. Because the algebra is closed, `union`, `intersection` and `complement` of schemas are schemas, and the relations between them are decidable on a published fragment. Both would go if the library grew the abilities above.
