# Refinements

A refinement narrows a base type to the subset satisfying one or more constraints. Write it with `Annotated[T, ...markers]`; the base `T` is checked first, then each constraint, except a length bound on a container, which is read before the elements it bounds (below). valgebra reads the [annotated-types](<https://pypi.org/project/annotated-types/>) markers by the module they come from, so it has no runtime dependency on that library; a marker another library writes for itself is that library's, and is [ignored](<#unrecognized-markers>).

That is a fact about valgebra, not about your environment: the **examples** on this page import `annotated_types`, and `pip install valgebra` does not bring it in. Install it alongside — `pip install annotated-types` — or write the same constraint with `valgebra.Regex`, which needs nothing beyond valgebra.

```
from typing import Annotated

import annotated_types as at

from valgebra import Validator

adult = Validator(Annotated[int, at.Ge(18), at.Le(150)])
assert adult.is_valid(21)
assert not adult.is_valid(5)
```

Refinements built from bound and length markers also take part in the [decision procedure](<https://ppigazzini.github.io/valgebra/explanation/decidability/index.md>): a refinement is a subtype of its base and of a looser refinement, and a bound conjunction that cannot be satisfied is detected as empty.

```
from typing import Annotated

import annotated_types as at

from valgebra import Validator

assert Validator(Annotated[int, at.Ge(0)]).is_subtype_of(int)  # refinement <= base
assert Validator(Annotated[int, at.Ge(0), at.Le(10)]).is_subtype_of(
    Annotated[int, at.Ge(0)]  # a tighter bound is a subtype of a looser one
)
assert Validator(Annotated[int, at.Ge(10), at.Le(0)]).is_empty()  # no such int
```

A predicate marker is checked at validation time, and nothing is inferred from it — its satisfiability is undecidable in general, so two refinements relate through a predicate only when they carry the same one. A decision query may still call it: asking whether a literal is a subtype of a refinement asks whether that literal's value belongs to it, which runs the predicate. A slow or side-effecting predicate is one `is_subtype_of` pays for. The answer stands for the literal only where its constant is its one value: `Literal[0.0]` also holds `-0.0` and `Literal[Decimal("1.00")]` holds `Decimal("1.0")`, which a predicate can tell apart, so such a literal below a predicate is not proven.

## Supported markers

| Marker | Constraint | Failure code |
| --- | --- | --- |
| `Ge(n)` | `value >= n` | `greater_than_equal` |
| `Gt(n)` | `value > n` | `greater_than` |
| `Le(n)` | `value <= n` | `less_than_equal` |
| `Lt(n)` | `value < n` | `less_than` |
| `MinLen(n)` | the value's length is `>= n` | `too_short` |
| `MaxLen(n)` | the value's length is `<= n` | `too_long` |
| `MultipleOf(n)` | `value % n == 0` | `multiple_of` |
| `Regex(p)` | the string fully matches the regex `p` | `string_pattern_mismatch` |
| `Predicate(f)` | `f(value)` is truthy | `predicate_failed` |

**A constraint is Python's own operation, and a value it raises against is refused.** The walk asks each constraint of the value and reads an ordinary error as a failed check, so a bound over a base holding values it cannot compare refuses them: `Annotated[int | None, Ge(0)]` admits the non-negative integers and refuses `None`, which orders against no number, with `greater_than_equal`. A length bound refuses a value with no length, and a pattern a value that is not a string, the same way:

```
from typing import Annotated

import annotated_types as at

from valgebra import Validator

maybe_count = Validator(Annotated[int | None, at.Ge(0)])
assert maybe_count.is_valid(3)
assert not maybe_count.is_valid(None)
assert maybe_count.relation_to(Annotated[int, at.Ge(0)]) == "subset"
```

**A length bound is read before the elements it bounds.** On a list, tuple, set, frozenset or dict, `MinLen` and `MaxLen` are asked once the value is of the base's kind and before any element is read, which is where a fixed shape such as `[int, int]` reads its length. A container too long for its bound is refused for its length alone, whatever it holds, and its elements are never walked, so the bound is a size guard too. The answer is the one either order gives, since a member satisfies both.

The guard holds where the bound and the elements are one refinement, as in `Annotated[list[int], at.MaxLen(3)]`. A bound carried in a meet of its own -- `intersection(list[E], Annotated[list, at.MaxLen(3)])`, or a validator in the metadata, which [builds that meet](<#a-validator-narrows-by-its-set>) -- is one member of the meet, and the meet reads its members in turn, so the elements of an over-long list are walked before the bound refuses it. The answer is the same; the cost is the length of the list, and the report names a bad element beside `too_long`.

```
from typing import Annotated

import annotated_types as at

from valgebra import ValidationError, Validator

capped = Validator(Annotated[list[int], at.MaxLen(3)])
raised = False
try:
    capped.validate([1, 2, "x", 4, 5])
except ValidationError as err:
    raised = True
    assert [item["code"] for item in err.errors] == ["too_long"]
assert raised
```

### Which base each marker can be asked of

A marker narrows a base by asking its values a question, so the base has to be one the question can be put to. This is which:

| Narrowing | The bases whose values answer it |
| --- | --- |
| `MinLen`, `MaxLen` | `str`, `bytes`, `list`, `tuple`, `set`, `frozenset`, `dict` — the kinds with a length |
| `Regex` | `str` — the kind with text for a pattern to match |
| `MultipleOf` | `bool`, `int`, `float` — the kinds with a number to divide |
| `Ge`, `Gt`, `Le`, `Lt` | every kind whose values compare **with the bound**: the numbers against a number, `str` against `str`, `bytes` against `bytes`, a list against a list, a tuple against a tuple, a set or frozenset against a set. Not `None` and not `dict`, whose values compare with nothing |
| `Predicate` | any base: the predicate is a black box and the value is handed to it whole |

A bound is the row to read twice, because it is the only marker whose answer depends on **both** values. `Annotated[set[int], Ge(0)]` is refused although a set has an order of its own, because a set and an integer do not compare; `Annotated[set[int], Ge({1})]` is the same base narrowed by a bound its values can be asked about, and it admits the supersets of `{1}`. A complex bound or step is refused with a `ValueError` when the validator is built: no value orders against a complex number or is a multiple of one. Two bounds over lists or tuples are not compared by the relations: a sequence orders item by item, so `[2 + 0j]` is at least `[2]` and orders against `[1]` not at all, which puts it in `Ge([2])` and out of `Ge([1])`. Two sets compare by inclusion and are decided, and so is a bound over `str` or `bytes`, the words on one side of a word being a regular set.

A marker put to a base outside its row is refused when the validator is built, for the reason above: the check would raise at every value, the walk reads a raise as a non-member, and the schema would admit nothing while reading like a narrowing. `tests/test_constraint_matrix.py` drives the whole of this table, cell by cell.

`Interval` and `Len` expand to the bounds they carry (below), and `Not` wraps a predicate. A marker from `annotated_types` that is **not** in this table names a constraint valgebra does not check — `Timezone` is the one — and is refused when the validator is built rather than ignored: ignoring it would leave a schema that admits exactly the values the marker was written to exclude. Two of the vocabulary's markers exclude no value and are ignored: `Unit`, which names what a number is measured in and leaves the reading to the consumer, and the documentation marker, so `Annotated[float, Unit("m")]` is `float`.

**A bound excludes `nan`.** Every comparison against a not-a-number is false, `>=` included, so a bounded float set never holds one while the bare kind does. This is the ordinary reading of the marker rather than a special case, and it is worth knowing because it is the one narrowing that removes a value the bound does not name.

```
from typing import Annotated

import annotated_types as at

from valgebra import Validator

nan = float("nan")

assert Validator(float).is_valid(nan)
assert not Validator(Annotated[float, at.Ge(0)]).is_valid(nan)
assert not Validator(Annotated[float, at.Le(0)]).is_valid(nan)
```

**A value has one length.** For a builtin container — a `list`, `tuple`, `str`, `bytes`, `set`, `frozenset` or `dict` — it is the number of items the value *holds*: the same number a sequence schema counts when it walks one. For any other value it is `__len__`. The distinction is visible only for a container subclass that overrides `__len__`: its `MinLen` is measured against what it stores, not against what it reports, so `Annotated[list[int], MinLen(5)]` and the shape `[int, int, int, int, int]` narrow by the same count. A length two parts of one schema disagreed about would not be a property of the value, and a set defined by one would not be a set.

A constraint must also be one the base can answer. Asking an `int` for its length raises, and a raise reads as a non-member, so `Annotated[int, MinLen(1)]` would denote *nothing at all* while looking like a narrowing. A constraint no value of the base can answer is therefore refused too; where some value can — a union with a `str` branch, or a class that may define what the constraint asks for — it is a narrowing and stands.

```
from typing import Annotated

import annotated_types as at

from valgebra import Validator

raised = False
try:
    Validator(Annotated[int, at.MinLen(1)])
except NotImplementedError as error:
    raised = True
    assert "length" in str(error)
assert raised

# One branch can answer it, so this narrows rather than empties.
narrowed = Validator(Annotated[int | str, at.MinLen(1)])
assert narrowed.is_valid("a")
assert not narrowed.is_valid(5)
```

The constraint narrows the whole union, so a branch whose values cannot answer it is left out rather than let through. That is the reading of `Optional` too: `Annotated[Optional[int], Ge(0)]` refuses `None`, where pydantic applies the bound to the `int` alone and admits it. Put the bound on the branch it narrows, and the `None` beside it stays:

```
from typing import Annotated, Optional

import annotated_types as at

from valgebra import Validator

whole = Validator(Annotated[Optional[int], at.Ge(0)])
assert not whole.is_valid(None)  # `None` has no order against `0`
branch = Validator(Optional[Annotated[int, at.Ge(0)]])
assert branch.is_valid(None)
assert branch.is_valid(3)
assert not branch.is_valid(-1)
```

`Regex` is valgebra's own marker (`from valgebra import Regex`), since `annotated-types` defines none for strings. The match is **anchored** — the whole string must match, like `re.fullmatch` — and runs natively in Rust with a linear-time engine (no catastrophic backtracking), so unlike a `Predicate` it stays on the fast path and never crosses into Python per value. An invalid pattern is rejected when the validator is built, not at first use, and a pattern is read on its own before it is anchored, so `a)|(b` is invalid rather than an alternation of two halves. A pattern matches the text of a string, and a string holding a lone surrogate -- which `json.loads` makes of an escaped `"\ud800"` -- has no such text, so it is outside every `Regex` refinement, and `str` is never below a pattern over it however much text the pattern matches ([what the soundness argument assumes](<https://ppigazzini.github.io/valgebra/explanation/soundness/index.md#what-this-argument-assumes>)). A compiled `re.Pattern` works as metadata too:

```
import re
from typing import Annotated

from valgebra import Regex, Validator

oid = Validator(Annotated[str, Regex(r"[0-9a-f]{24}")])
assert oid.is_valid("0123456789abcdef01234567")
assert not oid.is_valid("0123456789abcdef0123456X")  # not hex
assert not oid.is_valid("0123")  # not the full 24 characters

assert Validator(Annotated[str, re.compile(r"\d+")]).is_valid("123")

# A compiled pattern's flags are part of the pattern and are carried over.
assert Validator(Annotated[str, re.compile("abc", re.IGNORECASE)]).is_valid("ABC")
```

A pattern is matched against text, so a `bytes` pattern is refused. So are `re.ASCII`, `re.LOCALE` and `re.DEBUG`: the first two change what a character class means in ways this engine spells differently (see the dialect section below), and the third asks the other engine to report on itself. `re.IGNORECASE`, `re.MULTILINE`, `re.DOTALL` and `re.VERBOSE` are written into the pattern, which is how this engine spells them. `Regex` itself takes its pattern as a `str` and raises `TypeError` for anything else when it is made. It pickles and copies as the pattern it holds, so a schema carrying one can be sent to another process and built there, as [a validator cannot be](<https://ppigazzini.github.io/valgebra/explanation/boundaries/index.md#a-validator-does-not-pickle>).

### The dialect is Rust's, not `re`'s

Running natively is what buys the linear-time guarantee, and it is also what makes the dialect the Rust engine's. The two languages are close but not equal, and **a pattern both engines accept can denote different sets**. Compiling successfully is therefore not a test of which language a pattern is in. The places the two engines part, which a ported pattern should be checked against — this is where they differ, not a complete audit of what a pattern denotes:

```
import re
from typing import Annotated

from valgebra import Regex, Validator


def admits(pattern: str, text: str) -> bool:
    return Validator(Annotated[str, Regex(pattern)]).is_valid(text)


# POSIX bracket expressions. Python has no such class, so it reads a character
# class followed by a literal `]` and needs two characters.
assert admits(r"[[:alpha:]]", "a")
assert re.fullmatch(r"[[:alpha:]]", "a") is None
assert re.fullmatch(r"[[:alpha:]]", "a]") is not None

# Case folding. Both fold the ASCII pair; only Python folds the Turkish one.
assert admits("(?i)i", "I")
assert not admits("(?i)i", "\u0131")  # dotless i
assert re.fullmatch("(?i)i", "\u0131") is not None

# Property escapes. `\p{...}` is a pattern only this engine accepts.
assert admits(r"\p{L}+", "ab")

# Class-set operators. `--`, `&&` and `~~` combine classes here and are literal
# characters to Python, so a class carrying one is refused rather than read.
raised = False
try:
    admits(r"[\w~~\d]", "a")
except ValueError as err:
    raised = True
    assert "set symmetric difference" in str(err)
assert raised
# A nested set is refused for the same reason: a union here, four literals
# there.
raised = False
try:
    admits(r"[a[bc]]", "a")
except ValueError as err:
    raised = True
    assert "nested set" in str(err)
assert raised
# Word-boundary escapes. `\<` is the start of a word here and the character `<`
# to Python, so it is refused too.
raised = False
try:
    admits(r"\<b\>", "b")
except ValueError as err:
    raised = True
    assert "the start of a word" in str(err)
assert raised
```

Five more are quiet, and each is in a class or an anchor a ported pattern is likely to carry:

- **`\s`**: `re` counts the separators `\x1c` to `\x1f` as whitespace, as `str.isspace` does, and this engine follows Unicode's `White_Space`, which does not.
- **`\w` and `\b`**: this engine counts a combining mark as a word character and `re` does not, and `re` counts a numeric character that is not a decimal digit, such as `²`, and this engine does not.
- **`$`**: outside `MULTILINE`, `re` also matches `$` before a final newline, so `a$\n` admits `"a\n"` there and nothing here. `\z` is the end of the text in both, from Python 3.14.
- **`\B` on the empty string**: it matches here, and in `re` only from 3.14.
- **The Unicode version**: this engine's classes, case folding and properties are Unicode 16.0's, and `re`'s are the interpreter's own (`unicodedata.unidata_version`), 14.0 on Python 3.11 up to 17.0 on 3.15. A character one version assigns and the other does not is read apart: `\w` admits U+1C89, a letter 16.0 adds, here and in `re` from 3.14, and `(?i)` folds U+A7CE and U+A7CF, a case pair 17.0 adds, in `re` from 3.15 and not here.

```
import re
import sys
import unicodedata
from typing import Annotated

from valgebra import Regex, Validator


def admits(pattern: str, text: str) -> bool:
    return Validator(Annotated[str, Regex(pattern)]).is_valid(text)


assert not admits(r"\s", "\x1c")
assert re.fullmatch(r"\s", "\x1c") is not None

assert admits(r"\w", "\u0301")  # a combining acute accent
assert re.fullmatch(r"\w", "\u0301") is None
assert not admits(r"\w", "²")
assert re.fullmatch(r"\w", "²") is not None

assert not admits("a$\n", "a\n")
assert re.fullmatch("a$\n", "a\n") is not None

assert admits(r"\B", "")
assert (re.fullmatch(r"\B", "") is not None) == (sys.version_info >= (3, 14))

unicode = tuple(int(part) for part in unicodedata.unidata_version.split("."))
assert admits(r"\w", "\u1c89")
assert (re.fullmatch(r"\w", "\u1c89") is not None) == (unicode >= (16,))
assert not admits("(?i)\ua7ce", "\ua7cf")
assert (re.fullmatch("(?i)\ua7ce", "\ua7cf") is not None) == (unicode >= (17,))
```

The third of the first four is the loud case: `re.compile(r"\p{L}+")` raises, so a pattern that works here fails there and a reader finds out at once. The first two are the quiet ones — both engines build the pattern and answer differently — and they are the reason a library holding itself to `re`'s decisions cannot adopt `Regex` behind a fallback that triggers on compile failure.

The fourth is neither, because it is not accepted: a character class carrying `--`, `&&`, `~~` or a nested `[` raises a `ValueError` naming the operator, in the words `re` uses where it warns. `re` answers the four three ways: `[\w--\d]` raises, `[\w&&\d]` and `[\w~~\d]` warn that it may one day read them as operators, and `[a[bc]]` compiles without a word. This engine reads all four as operators now, so a pattern `re` accepts denotes two sets and nothing about compiling it says which. Refusing is the loud direction, and it is the one a reader can act on. Escape the characters to mean them literally — `[\w\~\~\d]` — or write the classes out. A POSIX class (`[[:alpha:]]`) is the one nested `[` that is read rather than refused, because it is the first divergence above and is documented there.

Verbose mode parts the two the same quiet way inside a class. `re.VERBOSE` keeps a space and a `#` there as members, and this engine ignores the space and starts a comment at the `#`. So under verbose mode -- `re.VERBOSE`, `(?x)`, or `(?x:...)` for one group -- a class carrying either raises a `ValueError` naming it. Escape it as `\` or `\#` to mean it, which both engines read as a member.

Three escapes part the two outside a class. `\<` and `\>` are the start and the end of a word here and the characters `<` and `>` to `re`, so `\<b\>` would admit `"b"` here and admits `"<b>"` there; `\b{start}` is a named word boundary here and, to `re`, a boundary followed by the text `{start}`. Each raises a `ValueError` naming what it asserts here. Write `<`, `>` or `\{` for what `re` reads, or `\b` for a word boundary in both.

Two quantifier spellings part them the same way. A `+` after a quantifier makes it possessive to `re` and repeats the quantified item again here, so `a?+` refuses `"aa"` there and would admit it here. And this engine reads a count with whitespace in its braces as the count -- `a{1, 3}` would admit `"aa"` -- where `re` reads a brace that is not exactly a count as text, and admits `"a{1, 3}"`; in verbose mode it skips a comment there too. Each raises a `ValueError` naming it. This engine has no possessive quantifier: write `(?:a?)+` to repeat the quantified item. Write a count without whitespace, or `\{` for the text.

A quantifier repeats an atom in `re`, and nothing else. This engine reads one on a quantifier and one on an assertion too: `a{2}{3}` as `a{6}`, `a**` as `(?:a*)*`, and `^*` as the empty match, where `re` refuses each, as a "multiple repeat" and "nothing to repeat". Each raises a `ValueError` in those words, so a pattern means nothing here that `re` cannot check. A `?` right after a quantifier makes it lazy in both, and only right after: in verbose mode, `a* ?` is a quantifier on a quantifier to `re`. Write a group, `(?:a{2}){3}`, to repeat a repetition, and leave an assertion unquantified.

**A pattern Python spells and this engine does not is refused**, which is the loud direction and the one to prefer. A lookaround (`(?=...)`, `(?<=...)`), a backreference (`\1`, `(?P=name)`), an atomic group (`(?>...)`), a conditional (`(?(1)...|...)`), an inline comment (`(?#...)`), a named character (`\N{BULLET}`), the ASCII flag `(?a)`, the `\Z` anchor and the open-ended `{,n}` repetition all raise a `ValueError` naming the parse error, rather than being read as something else.

### Agreement with `re` is not ASCII

Checking a pattern against the list above tells you the two engines agree. It does not tell you the pattern denotes what you meant, and the character classes are where that bites: `\d`, `\w` and `\s` are **Unicode-aware** here, exactly as they are in `re`. The two engines agree, and a reader who wanted digits gets every decimal digit Unicode defines.

```
import re
from typing import Annotated

from valgebra import Regex, Validator

year = Validator(Annotated[str, Regex(r"\d{4}")])
assert year.is_valid("٢٠٢٦")  # Arabic-Indic digits are decimal digits
assert re.fullmatch(r"\d{4}", "٢٠٢٦") is not None  # `re` agrees

assert Validator(Annotated[str, Regex(r"\w")]).is_valid("é")
assert Validator(Annotated[str, Regex(r"\s")]).is_valid("\u00a0")  # no-break space
```

Write the ASCII set when you mean the ASCII set. `[0-9]` is the portable spelling; `(?-u:\d)` is the same thing with the Unicode flag turned off for that group, and is this engine's syntax rather than `re`'s:

```
from typing import Annotated

from valgebra import Regex, Validator

assert not Validator(Annotated[str, Regex(r"[0-9]{4}")]).is_valid("٢٠٢٦")
assert not Validator(Annotated[str, Regex(r"(?-u:\d){4}")]).is_valid("٢٠٢٦")
assert Validator(Annotated[str, Regex(r"[0-9]{4}")]).is_valid("2026")
```

This is the shape that reaches production: a timestamp, an identifier or a version pattern written with `\d` admits strings the parser downstream rejects, and every engine involved agrees the pattern is fine.

A bound against `nan` is rejected with a `ValueError`, and so is `MultipleOf(nan)`: every comparison with `nan` is false, so such a bound admits no value at all. A `Decimal` not-a-number is rejected the same way, quiet or signaling: every comparison and remainder with `Decimal("sNaN")` raises `InvalidOperation`, which the walk reads as a refusal. That is the empty set written as a bound, which no caller means, and dropping the marker instead would admit every value of the base. A complex bound is rejected for the same reason, whatever its imaginary part: Python orders no value against a complex number, and `1 >= 0j` raises. A bound that is empty because the *order* says so — `Gt(inf)` on a float — is kept, because emptiness is then an answer rather than the absence of one.

A float under a `Decimal` bound is compared as the `Decimal` it equals, `Decimal.from_float`, which is exact. Python compares a float with a `Decimal` exactly too, but through the thread's `decimal` context, and a `FloatOperation` trap there makes the comparison raise: read through it, `0.75` would be outside `Ge(Decimal("0.25"))` in a thread that sets the trap and inside it in one that does not. The set is the one the bound writes, whatever the context. A subclass of `float` keeps its own comparison, which may be code of its own, so it meets the bound as Python compares it, context included:

```
from decimal import Decimal, FloatOperation, localcontext
from typing import Annotated

import annotated_types as at

from valgebra import Validator

at_least = Validator(Annotated[float, at.Ge(Decimal("0.25"))])
with localcontext() as context:
    context.traps[FloatOperation] = True
    assert at_least.is_valid(0.75)
    assert not at_least.is_valid(0.1)
```

`MultipleOf(n)` requires a nonzero **number**: no value is a multiple of zero, so `MultipleOf(0)` is an unsatisfiable constraint, and a step that is not a number is unsatisfiable for the same reason one step further on. The constraint is `value % n == 0`, and a remainder that is not a number equals no zero — `timedelta(6) % timedelta(2)` is `timedelta(0)`, which is not the integer `0` — so such a step names a schema no value belongs to. Both are rejected with a `ValueError` when the validator is built, rather than rejecting every value at check time, and so is a complex step, since Python takes no remainder against a complex number. `int`, `float` and `Fraction` steps divide every number as they read. A `Decimal` step divides an integer and not a float, because `%` refuses to mix a float and a `Decimal`: `Annotated[float, MultipleOf(Decimal("0.5"))]` is rejected with a `NotImplementedError`, and over `int | float` the step narrows the integers.

`typing` caches `Annotated` by equality, and `MultipleOf(2 + 0j)` equals `MultipleOf(2)` as `MultipleOf(Decimal("0.5"))` equals `MultipleOf(0.5)`. In a process that built the complex or `Decimal` spelling first, the real one arrives as it and is rejected with it; the message says so. A whole float step equals the integer one too, and is not the same set over the integers: `%` reads an `int` against a `float` as the float nearest it, so `MultipleOf(2.0)` admits `2**53 + 1`, whose nearest float is `2**53`, and `MultipleOf(2)` does not. In a process that wrote `MultipleOf(2.0)` first, `Annotated[int, MultipleOf(2)]` is that marker and admits `2**53 + 1` as well, with nothing to say so, since both are valid. Write a step over the integers as an `int`. The step is read as the number it is, not by its value: reading `2.0` as `2` would refuse a value the marker's own `%` admits.

**A float step is exact.** `value % n == 0` is Python's own `%`, with no tolerance added, and a binary float holds no `0.1`: `0.3 % 0.1` is `0.09999999999999998`. So `Annotated[float, MultipleOf(0.1)]` admits `0.1` and `0.2` and refuses `0.3` and `1.0`. A `Fraction` step over a float is the same `%`, which turns the fraction into the float nearest it: `3.0 % Fraction(1, 3)` is `1.6653345369377348e-16`, so a step of a third admits `1 / 3` and refuses `3.0`. A step meant in decimal places wants a decimal base, whose `%` is exact in those places:

```
from decimal import Decimal
from fractions import Fraction
from typing import Annotated

import annotated_types as at

from valgebra import Validator

tenths = Validator(Annotated[float, at.MultipleOf(0.1)])
assert tenths.is_valid(0.2)
assert not tenths.is_valid(0.3)  # 0.3 % 0.1 is not 0.0
thirds = Validator(Annotated[float, at.MultipleOf(Fraction(1, 3))])
assert thirds.is_valid(1 / 3)
assert not thirds.is_valid(3.0)  # 3.0 % Fraction(1, 3) is not 0.0
decimal_tenths = Validator(Annotated[Decimal, at.MultipleOf(Decimal("0.1"))])
assert decimal_tenths.is_valid(Decimal("0.3"))
assert not decimal_tenths.is_valid(Decimal("0.15"))
```

The compound markers `Interval` and `Len` expand to the bounds they carry, so `Interval(ge=0, le=10)` contributes `Ge(0)` and `Le(10)`, and `Len(2, 4)` contributes `MinLen(2)` and `MaxLen(4)`. A `Len` whose minimum is below zero is refused as a `MinLen` of it is, although `annotated_types` unpacks it to no lower bound at all. A length is a whole number, and Python compares one with a `float`, a `Fraction` or a `Decimal` exactly, so a length bound equal to a whole number is that length: `MaxLen(2.0)`, `MaxLen(Fraction(2))` and `MaxLen(True)` are `MaxLen(2)` and `MaxLen(1)`, which `typing`'s cache would hand them anyway, and a bound equal to no whole length, `MaxLen(2.5)`, is refused. So is a number of any other type, a subclass of those three included, whose `int()` and `==` are its own code rather than the arithmetic `len` is compared by. So is a length past `sys.maxsize`: CPython counts a length in a `Py_ssize_t` and `len()` raises past it, so no value is longer, and `MinLen(2**63)` would be the empty set written as a bound. They are read through the grouping protocol `annotated_types` documents — a marker that stands for several constraints answers for them — so **a marker of your own written that way is read the same way**:

```
from typing import Annotated

import annotated_types as at

from valgebra import Validator

assert Validator(Annotated[int, at.Interval(ge=0, le=10)]).is_valid(5)
assert not Validator(Annotated[int, at.Interval(ge=0, le=10)]).is_valid(11)
assert Validator(Annotated[str, at.Len(2, 4)]).is_valid("abc")
assert not Validator(Annotated[str, at.Len(2, 4)]).is_valid("a")


class Percent(at.GroupedMetadata):
    """A marker of your own, standing for the two bounds it yields."""

    def __iter__(self):
        yield at.Ge(0)
        yield at.Le(100)


assert Validator(Annotated[int, Percent()]).is_valid(50)
assert not Validator(Annotated[int, Percent()]).is_valid(101)

assert Validator(Annotated[int, at.MultipleOf(3)]).is_valid(9)
assert not Validator(Annotated[int, at.MultipleOf(3)]).is_valid(5)
```

## Predicates: the slow path

A `Predicate` runs an arbitrary Python callable. It is the one *refinement* constraint that leaves Rust for a caller's own code — literals, instance and attribute checks, and comparison bounds also compare against Python objects, but against fixed operators, not arbitrary callables — so it is a **documented slow path**, never a silent fallback. `is_valid` runs it once per value it reaches, and stops at the first value that fails. `validate` explains as it decides, in one walk, except at a union: a refused union walks each branch it has to once to decide whether any branch admits the value and again to explain it, so a predicate inside runs twice there, and a union left with one branch to walk explains it once. A dict schema -- a record, a `TypedDict`, a mapping -- that refuses a value is read twice: a deciding pass, then an explaining pass. A record -- closed, a `TypedDict`, or open under a catch-all clause that reads its values -- is read by its keys, and resumes at the field the first pass stopped at, so a predicate on or under that field runs a second time, and past its fields where an undeclared key refused it. A mapping is read by a scan, and its explaining pass starts at the first entry: a predicate on every entry up to the refused one runs a second time. A predicate on the clause an undeclared key falls under runs once to find whether the clause covers the entry and again to report it (`docs/dev/walk.md`). A dict schema that is a branch of a union is read the second time only where no branch admits the value. Without `fail_fast`, `validate` also reads past the first failure, running the predicate on values `is_valid` never reached. A predicate is user code, and every occurrence the walk reaches is a call -- two equal occurrences in one meet or union are one occurrence, deduplicated when the schema is built, so `Annotated[int, f, f]` calls `f` once a value. The walk keeps no cache over it, because a cache would change what a predicate that does not answer from its value alone observes, and the same reading is what keeps `A & ~A` from folding when `A` carries one. A predicate that must run once per value memoizes on its own side. Use it for checks the markers cannot express:

```
from typing import Annotated

import annotated_types as at

from valgebra import Validator

even = Validator(Annotated[int, at.Predicate(lambda x: x % 2 == 0)])
assert even.is_valid(4)
assert not even.is_valid(3)
```

A predicate that *raises* is reported distinctly, as `predicate_error` rather than an ordinary failure, so a buggy predicate is not mistaken for a rejected value.

A bare callable is a predicate too, without the wrapper:

```
from typing import Annotated

from valgebra import Validator

positive = Validator(Annotated[int, lambda value: value > 0])
assert positive.is_valid(1)
assert not positive.is_valid(-1)
```

`Predicate` is the portable spelling — pydantic reads it — so prefer it in an annotation other tools also consume. The bare form is valgebra's own convenience, and it excludes a class, which [is never read as a marker](<#unrecognized-markers>): calling one constructs rather than asks.

### A bare callable is metadata only

The bare form is read **only** in `Annotated` metadata position, and reading it there at all is valgebra's own convenience: the libraries that share this metadata channel require a wrapper — pydantic `AfterValidator`, beartype `Is[...]`, `annotated_types` `Predicate` — and msgspec reads no callable at all, since its `Meta` carries none. The typing spec leaves each consumer to say what its own metadata means, so this arm reaches exactly as far as the metadata position and no further.

A schema language that reads a top-level callable as a predicate is expressing a different rule for a position `Annotated` metadata does not cover; valgebra's rule for that position is the one below.

A **typing form** in metadata is not a predicate either, although every one is callable: calling `list[int]`, a `NewType` or an `Annotated` alias with a value builds something rather than answering whether the value belongs. A typing form is metadata this frontend does not recognize and is ignored, as a class is. An `Annotated` alias carrying a marker this page reads -- `at.IsFinite`, or an alias of your own over `at.Gt(0)`, written as an assignment or with the `type` statement -- is refused rather than ignored: it carries its markers for the type it annotates, and in metadata it annotates nothing, so it was written where its type was meant:

```
import math
from typing import Annotated

import annotated_types as at
import pytest

from valgebra import Validator

with pytest.raises(NotImplementedError, match="is an Annotated alias"):
    Validator(Annotated[float, at.IsFinite[float]])

finite = Validator(at.IsFinite[float])  # the alias, as the type
assert finite.is_valid(0.0)
assert not finite.is_valid(math.inf)
```

PEP 702's `deprecated` is ignored the same way. `typing_extensions.deprecated` is that module's own below 3.13 and the standard library's `warnings.deprecated` from it, and on every release `Annotated[int, deprecated("...")]` is `int`.

**A decorator function is called.** What this frontend tells apart from a predicate is an *object* whose class is a typing form or the standard library's `deprecated`. A function is a function, and nothing about one says whether it asks or decorates: `math.isfinite` and `typing.final` are both the standard library's. So a decorator in metadata is called with the value. `dataclasses.dataclass`, `abc.abstractmethod` and `typing.no_type_check` raise for a value that is neither a class nor a function, and refuse every value; `typing.final` and `typing.override` return what they are given, and refuse `0`:

```
import typing
from typing import Annotated

from typing_extensions import deprecated

from valgebra import Validator

assert Validator(Annotated[int, deprecated("use the account id")]) == Validator(int)

final = Validator(Annotated[int, typing.final])  # called, as a predicate is
assert final.is_valid(5)
assert not final.is_valid(0)
```

Passed as a schema on its own, a callable is **refused**. Read as the [fallback literal](<https://ppigazzini.github.io/valgebra/guides/schema-language/index.md#anything-unrecognized-is-a-literal>) reads an object, it would denote the one function object, and `intersection(Record, kind_is_known)` would be a schema admitting nothing that nothing reports: `is_empty` answering `False` is "no, or not yet proven" (see the [decidability boundary](<https://ppigazzini.github.io/valgebra/explanation/decidability/index.md#the-contract>)), and the meet of a record with a function object's literal is one it does not decide. The refusal names the two spellings that were meant, the refinement as `Annotated` and the constant as `Literal`:

```
from typing import Annotated, TypedDict

import pytest

from valgebra import Validator, intersection


class Record(TypedDict):
    kind: str


def kind_is_known(value):
    return value["kind"] in {"a", "b"}


with pytest.raises(NotImplementedError, match="a callable is not a schema"):
    intersection(Record, kind_is_known)

refined = Validator(Annotated[Record, kind_is_known])  # the refinement
assert refined.is_valid({"kind": "a"})
assert not refined.is_valid({"kind": "z"})
```

`annotated_types.Not` wraps a predicate and denotes the values it rejects:

```
from typing import Annotated

import annotated_types as at

from valgebra import Validator

odd = Validator(Annotated[int, at.Not(lambda value: value % 2 == 0)])
assert odd.is_valid(3)
assert not odd.is_valid(2)
```

A marker that is itself callable is **called**, which is what applies `Not`'s negation and what keeps a `functools.partial`'s bound arguments. Only a marker that is not callable is taken apart by its `.func`, which is the shape `Predicate` has.

## On classes

Refinements declared on a `TypedDict`, dataclass, or `NamedTuple` field are enforced — the constraint travels with the field:

```
from typing import Annotated, TypedDict

import annotated_types as at

from valgebra import Validator


class Account(TypedDict):
    balance: Annotated[int, at.Ge(0)]


assert Validator(Account).is_valid({"balance": 100})
assert not Validator(Account).is_valid({"balance": -1})
```

## A validator narrows by its set

A compiled validator in the metadata is a set, and `Annotated[T, v]` denotes the values of `T` that `v` admits: the meet of `T` and `v`, the set `intersection(T, v)` builds. Beside other markers it is met with the refined base, and a grouped marker that yields one is read the same way. This is the spelling for a class field whose set typing cannot express: a static checker reads the field as `T`, and the validator refuses what `v` refuses, in the Rust walk and not through a Python callback.

```
from dataclasses import dataclass
from typing import Annotated

from valgebra import Validator, complement, intersection

non_bool_int = intersection(int, complement(bool))


@dataclass
class Row:
    count: Annotated[int, non_bool_int]


rows = Validator(Row)
assert rows.is_valid(Row(3))
assert not rows.is_valid(Row(True))  # a bool is an int, and not a member
assert Validator(Annotated[int, non_bool_int]) == intersection(int, non_bool_int)
```

## Unrecognized markers

Per the typing spec, metadata valgebra does not recognize as a constraint is ignored — so non-constraint `Annotated` metadata, such as a documentation string, is harmless and carries no membership meaning. The carve-out is the `annotated_types` vocabulary itself: a marker from there was written to narrow *this* schema, so one valgebra does not check is refused rather than ignored. A validator is not unrecognized metadata at all: it narrows by its set, above.

A constraint is read off the vocabulary's markers, `Regex` and a compiled `re.Pattern`, and off nothing else, whatever its attributes are called. msgspec's `Meta`, pydantic's `Field` and `AfterValidator`, and a class of your own may carry a `ge` or a `pattern` and mean what their own library means by it — msgspec and pydantic search with a pattern where valgebra matches it whole — so each is ignored, as pydantic ignores msgspec's metadata and msgspec pydantic's. A library joins the vocabulary the way its README says, as a `GroupedMetadata` yielding the vocabulary's markers, and those are read; a class derived from one of the vocabulary's is read as the class it derives from. Its bounds are read as its attributes are, through a `__getattribute__` of its own where it has one, and once a class: which names a marker class answers is read the first time a marker of it is built into a validator and kept for the process, so a class given a bound after that keeps the reading it was first given.

```
from typing import Annotated

from valgebra import Validator


class Minimum:
    """Another library's marker, carrying a name the vocabulary also uses."""

    def __init__(self, ge: int) -> None:
        self.ge = ge


assert Validator(Annotated[int, Minimum(0)]) == Validator(int)
assert Validator(Annotated[int, Minimum(0)]).is_valid(-1)
```

A **class** is never read as a marker. A marker carries its values on an instance — `Ge(0)` holds `ge = 0` — so the class itself holds no value to read and calling it constructs rather than asks. A marker class written where its instance was meant is refused with the spelling that was meant, since ignoring it would leave the schema its base; any other class, such as a unit or an enumeration, is ignored:

```
from typing import Annotated

import annotated_types as at

from valgebra import Validator

try:
    Validator(Annotated[int, at.Ge])
except NotImplementedError as err:
    assert "so write Ge(...)" in str(err)
else:
    raise AssertionError("a marker class is refused")
```

```
from typing import Annotated

from valgebra import Validator

assert repr(Validator(Annotated[int, "a documentation note"])) == "int"
```
