Skip to content

Versioning, and what counts as a break

The version follows Semantic Versioning, and while the line is 0.x the minor number is the breaking one: 0.1.0 to 0.2.0 may break, 0.1.0 to 0.1.1 may not. Below 0.1.0 there is no minor number to carry a break, so every 0.0.x release may break, and its notes say where. The line stays on 0.0.x for a long time, so a break does not wait for 0.1.0: it ships in a 0.0.x release, after the warning below.

What a break means here is specific, because a validator has two surfaces and only one of them is the API:

  • A break. A value that validated and no longer does, or a value that did not and now does. An error code or a violation path that changes for a failure that was already reported. A name removed or renamed, a parameter that stops accepting what it accepted, an exception type that changes.
  • Not a break. A relation that answered False ("not proven") and now answers True. The conservative answer is documented as "no, or not proven" (decidability) -- so code that treats False as a proof of the negative was reading a guarantee that was never given. Widenings are listed in the notes below, and they are the commonest entry.
  • Not a break, and worth reading anyway. A repr that changes, an expected string reworded, a message improved. They are described in the notes because tests pin them, and pinning one is a choice to be told.

Deprecation

A name on its way out keeps working, and warns, for at least three releases: calling it emits a DeprecationWarning naming what replaces it, and the notes below carry an entry saying it is going. A later release removes it, and its notes say so.

Nothing is removed without that window, and nothing that warns is left warning indefinitely -- a warning that never resolves is a cost with no end, and a removal with no warning is a break a reader had no way to see coming.

Changelog

All notable changes to valgebra are recorded here. The format follows Keep a Changelog, and the project follows Semantic Versioning.

Unreleased

Added

  • A pattern's word lengths decide a length bound. The least and the most length of the strings a Regex matches are read off its automaton, so a pattern on a str is below a MaxLen or a MinLen its strings keep to and outside one a string breaks, at every bound: Annotated[str, Regex("[a-f0-9]{24}")] is subset of Annotated[str, MaxLen(n)] for every n from 24, and Annotated[str, Regex(".*-x")] not_subset of every MaxLen, where each stayed undecided past a few hundred characters, the bound's own automaton no longer fitting its states. A bound a pattern keeps to changes no string of it, so the meet of the two is the pattern, below the same patterns the pattern alone is below. Against 0.0.31's recording no decision is lost and none is slower.

  • A union's branch that is a meet of atoms is one clause. A meet the rules decline is distributed across its unions where its normal form spans four clauses at most, and a union whose branch was a meet counted past any bound, so such a meet was never distributed. A branch that is a meet holding no union and no meet is the one clause its members join, so w implies w and t spelled union(intersection(has("w"), has("w", "t")), complement(has("w"))) reads as its flat spelling does: met with a record whose field holds a predicate, which keeps the record from the set representation, it is not_subset of nothing, where it stayed undecided.

  • A meet holding a union is asked as its clauses once all else declines. A relation every asking leaves undecided whose subject is a meet holding a union is asked once more, a budget of its own, with each meet holding a union read as the union of its clauses, one union at a time: below a supertype where every clause is, and outside it where one clause is. Z & (X | Y) is related as (Z & X) | (Z & Y) is, so a oneOf of two pairs a translation from JSON Schema writes, {"oneOf": [{a: 1, b: 1}, {a: 2, b: 2}]} beside required: ["a", "b"], is subset of if a = 1 then b = 1 else b = 2, and a meet subject below a meet supertype where it is below each member, where each stayed undecided. The asking before it is unchanged, so no answer it gives moves; against 0.0.31's recording no decision is lost and none is slower.

0.0.31 - 2026-11-21

A release of answers and speed, with no node. Where the deciders declined, a pair is now refuted on a value guessed from its subject or aimed outside its supertype, a meet reads a complement pushed in, a branch in its clause, a guard beside a member of its kind and a meet among a key's types, records met over a guarded fixpoint are related as one record, and a length bound beside a record leaves the record it counts. Over the 70,000 pairs each generation of a fuzzer draws, the relations give 1,570 answers more than 0.0.30 on the first generation, 3,491 on the second and 2,923 on the fourth, and lose none, and no call is ten times slower past 50 ms; the families of exact relations over lists, records, mappings, TypedDicts and recursions give 19,269 more and lose none. Read through valgebra-jsonschema, the JSON Schema test suite and corpus studies move no count, and the containment study decides 65 questions more, 64 refutations and a proof: of the 36 refutations against the suite's labels, the 35 in draft 4 stand on a const, which draft 4 does not have, and the one in 2020-12 on {"bar": {"baz": {}}}, which jsonschema and jsonschema-rs both admit in a subject the suite labels unsatisfiable. valgebra-vtjson's differential suite passes.

Against 0.0.30 built here from its tag, on CPython 3.11 through 3.15, a list of floats under order bounds counts 42.5% to 49.4% fewer instructions on the profiled wheels, a list of strings under a pattern 15.0% to 16.6% fewer and a record of refined fields 0.7% to 1.0% fewer, and a relation between two dataclasses reads 40.8% fewer on 3.15 and 3.12. Every other shape counts within 0.5% of 0.0.30's but seven, each of which reads the same in an environment 4,096 bytes larger: on 3.13 a JSON document's integers, union and refusal 2.0% to 4.3% more, the copy a realloc makes as the parser grows the document's array from empty; on 3.15 a deep JSON document 1.41% and a list's explanation 0.54% more; on 3.11 a union's build 0.99%, a scalar's explanation 0.76% and a dataclass 0.55% more, in glibc's allocator. The instruction gate's ten decision workloads count within 0.2% of 0.0.30's.

Added

  • A pair the deciders decline is refuted on a value guessed from the subject. Where neither the rules nor the set representation decides a relation and the subject denotes more values than the finite reading builds, the relation guesses up to 64 small values from the subject's spelling -- a value of each scalar kind it names, each of its constants, the sequences, sets and dicts its items and fields guess, three containers deep, and a reference read through its definition -- and walks each through both schemas. A value the subject admits and the other schema refuses refutes the pair: the JSON fixpoint is not_subset of ~list | list[~list | Annotated[list[Any], MaxLen(1)]] on [[None, False]], a fixpoint over tuple[complement(t), t] of its swap on (None, 1), and dict[float, int] of dict[Literal[1.0], int] on {0.5: 0}, where each stayed undecided. The guesses prove nothing, so an inclusion is never decided by them. Over 4,000 pairs of recursive schemas drawn over eleven leaves, 36 of the 62 relations 0.0.30 left undecided are refuted, and no answer it gave moves. On the containment suite of Attouche et al. read through valgebra-jsonschema, 8 more questions are refuted, 5 against the suite's labels: four where draft 4's missing const leaves the subject every value, and one 2020-12 pair labeled empty whose refuting value {"bar": {"baz": {}}} jsonschema and jsonschema-rs both admit.

The readings that walk a value -- this one and the finite reading's -- read a bound or a step only where its operand is an exact int, bool or float, or the standard library's Fraction or Decimal: a class of the program's own compares by its code, which a second call may answer anew.

  • A pair is refuted on a value aimed outside the supertype. Beside the values it guesses from the subject's spelling, the relation builds values aimed outside the supertype, its negation pushed one constructor in as a witness generator for JSON Schema pushes it through each operator (Attouche et al., Witness Generation for JSON Schema, PVLDB 2022, §5.2): outside a list of X, a list holding one value outside X; outside a sequence no item may follow, one item more; outside a record, a dict lacking a required key, holding a field outside its type, or holding a key the record closes out; outside a bound, a number beside it; outside a constant, the integer or the string beside it; outside a complement, its operand's members; and one value of each other kind. A complement in the subject is guessed the same way. Each is walked through both schemas, so a value wide of the difference refutes nothing, and the relation still walks at most 64 values. The JSON value fixpoint is not_subset of JSON Schema's dependencies as a translation spells it, on {"bar": None}. On the containment suite of Attouche et al. read through valgebra-jsonschema, 41 more draft-4 questions are refuted, 23 against the suite's labels; in each of those const, which draft 4 does not have, leaves the subject every value, and jsonschema and jsonschema-rs place the refuting value inside it and outside the supertype. Of the 28 undecided questions the suite labels refutations, 17 remain, each against a supertype the companion spells with a predicate, whose code the reading does not run.

  • Records met over a guarded fixpoint are related as one record. Two records met are their field-by-field meet, and a field's meet is now decided where a reference stands in it: a field one record guards to its kind over the JSON values, ([T] | ~list) & json, met with [str], is below [T], since a list of strings is no value of ~list. That is the field a translation from JSON Schema writes for an allOf member narrowing an array's items, and {"tags": [str]} met with {"tags?": ([Literal["a"]] | ~list) & json} is subset of {"tags": [Literal["a"]]}, where it was undecided. A goal the rules decline is read by the set representation where it holds a reference and a meet, a union or a complement tops one side; one a constructor or a reference tops on both sides is left to the rules, which take it apart. Against 0.0.30's recording, two more decisions are made, none is lost and none is slower. On the containment suite read through valgebra-jsonschema, 15 more draft-4 questions over uniqueItems are refuted, 8 against the suite's labels: in each const, which draft 4 does not have, leaves the subject every value, and jsonschema and jsonschema-rs admit [1] there and refuse it in the supertype.

  • A guard beside a member of its kind is dropped from a meet. The complement of a container of anything -- ~list[Any], ~dict[Any, Any] and the like -- holds no value of the container's kind, so beside a member of that kind alone it is dropped from its union, the meet being the same set: list[str] & ([T] | ~list) is read as list[str] & [T], and {"a": int} & (R | ~dict) as the record met with R. That is the guard a translation from JSON Schema writes for a keyword of one kind, beside the object or array it spells as a record or a list, and the form valgebra-jsonschema compiles an allOf member narrowing an array field's items to, {"tags": [str], str: json} & ({"tags?": ([T] | ~list) & json, str: json} | ~dict) & json, is subset of {"tags": [T]}.open(), where it was undecided. A branch that is no such guard is not dropped by its kinds. On the containment suite read through valgebra-jsonschema, one more 2020-12 question is proven, as the suite labels it; against 0.0.30's recording no decision is lost and none is slower.

  • A meet reads a complement among its members pushed in, and a union's branch in its clause. Where a meet is related to a supertype, a member that is the complement of a union is read as its branches' complements, and one that is the complement of a meet all of whose conjuncts but one are members as that conjunct's complement, where that narrows the meet. A union's branch that is a meet is read beside the members its clause holds: dropped where one of its conjuncts shares no value with them, its own unions narrowed the same way. And the complement of a reference shares no value with a member its definition holds as a branch. Each reading leaves the same set. They are the shapes a translation from JSON Schema writes beside an object -- not X as ~X & J, J the JSON values, if I then T as (~I & J) | (I & T & J), and anyOf and oneOf as unions of meets each holding J, every keyword guarded to its kind -- so the object a not not, not anyOf, if/then or anyOf requires k of is subset of {"k": anything, str: anything}, where each was undecided, and so is one a oneOf requires it of whose one branch excludes a key the other requires. A meet read for its emptiness takes neither reading, since its narrowed meet is asked before the distribution of the meet as written. On the containment suite and the corpus read through valgebra-jsonschema no answer moves, and against 0.0.30's recording no decision is lost and none is slower.

  • A length bound beside a record leaves the record it counts. A record under a length bound that counts its names is read as the record those leave: a least length counting every name of a closed record requires each, and a greatest length counting its required names admits no other key, so Annotated[{"a?": int}, MinLen(1)] is subset of {"a": int}. A bound over every dict met with records reads the one record they meet into the same way, and one mapping keyed by words beside it goes to the count of its words: dict[Literal["k"], Any] & Annotated[dict[str, Any], MinLen(1)] is subset of {"k": anything, str: anything}, where it was undecided. That is how a translation from JSON Schema writes minProperties and maxProperties beside an object, and propertyNames spelled as the closed record of its names, so presence through a minProperties counting an object's every possible name, and absence through a maxProperties counting its required ones, is decided. A bound counting fewer names proves nothing of any one of them; the relation takes only proofs through the record, and a refined record's emptiness is read off it. On the containment suite and the corpus read through valgebra-jsonschema no answer moves, and against 0.0.30's recording no decision is lost and none is slower.

  • A meet among a key's types is read beside the key's other types. Records met hold no value where a key one of them requires has types meeting in nothing, and a type that is itself a meet is now spliced into that meet, so a field one record guards to its kind, ([T] | ~list) & json, is read in its clause beside the others. {"tags": [str]} met with {"tags?": ([Literal["a"]] | ~list) & json} and a record requiring a list of at least one "c" is empty, where it was undecided: the tags are strings, "a" and "c" at once. On the containment suite and the corpus read through valgebra-jsonschema no answer moves, and against 0.0.30's recording no decision is lost and none is slower.

  • How it works. The explanation opens with a page that follows one schema from its annotation to both answers: the frontend and the normal form, the walk that answers membership in one call into Rust over the object held, and the deciders that answer inclusion with subset, not_subset or undecided; where valgebra sits beside a parser, a static checker and its two companions; and what it does not cover. Each step has a diagram, a mermaid block the site draws in its own palette, light or dark, and GitHub draws from the same text, and its examples run as written.

Changed

  • The documentation site is built by Zensical. Material for MkDocs, which reaches its end of life on 2027-05-05, gives way to Zensical, its maintained successor, which builds the site from the same mkdocs.yml under zensical build --strict: its own search, the redirects from each page's former address, the llms.txt manifest and the llms-full.txt export, the Mermaid diagrams and the mkdocstrings API reference. No page moves.

  • A relation keeps what it read of a class. A refutation about a class reads what a direct instance of it can carry off the namespaces of its __mro__, and a class's own reading is now kept across relations and taken where the namespace still holds the same names, each read as the same member, so an assignment to the class between two relations is read as it stands. A refutation between two dataclasses reads 40.8% fewer instructions on CPython 3.15 and 3.12. The kept readings hold strings alone, so a class a program drops is freed as it would be.

  • A predicate's stack check is one subtraction. On CPython before 3.14 the walk asks, before it calls a predicate, whether the thread's stack has room for the Python it runs, and that question now reads 7 instructions where it read 17: a thousand integers under a predicate read 5.0% fewer instructions on CPython 3.12.

  • A list of strings under one pattern reads the pattern once. A list whose element is a str under one pattern, alone or beside length bounds, finds the pattern's compiled program once for the list, where each element's check looked it up: two hundred strings under one pattern read 15.3% fewer instructions on the profiled CPython 3.12 wheel, and 15.0% fewer than 0.0.30's.

  • A list of floats under order bounds is read as one interval. Where every constraint of a float element is an order bound whose operand a float holds exactly, the bounds are read once for the list, each end open or closed, and an exact float is its two comparisons, where it went through the constraints' loop and read its operand at every element: a thousand floats under one bound read 43% to 49% fewer instructions on the profiled wheels of CPython 3.11 to 3.15 than 0.0.30's. A single float under such a bound 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. Every answer and every report is the one the comparisons give.

Fixed

  • Opening or closing a recursive placeholder is refused. open() and close() reach a fixpoint's records through the reference to its definition, and the placeholder a builder is handed names a definition not built until the builder returns. Both left the placeholder as it was, so recursive(lambda t: union(None, {"k": Validator(t).open()})) was the fixpoint built without .open(), refusing {"k": {"k": None, "z": 1}}, which its body written out around it admits; a record holding the placeholder, opened or closed beside a record left as declared, built another set the same way. Both now raise ValueError on a schema holding a placeholder, in its root or in a definition. A call that returned now raises: open the validator recursive returns, or write anything: anything into the record where it is declared.

  • A walk on PyPy under a lowered recursion limit asks for room before its question can overflow. PyPy sizes the stack its C-API calls may use by the recursion limit, and the walk asks __pypy__.stack_almost_full from a frame kept free below it, once it has gone a step deeper than the last answer. With a 2 KiB step and a 16 KiB reserve that frame could land past PyPy's threshold, where the question itself overflowed inside cpyext and ended the process: explaining a list nested 1,600 deep or a JSON value twelve lists deep did so on PyPy 3.12 under limits of 38, 41 and 53, and on PyPy 3.11 under 37, 38, 40, 42 and 43. The walk asks every 1 KiB from 12 KiB below it, and under every limit from 37 to 120 no process ends on either; a value deep enough to cross a step reads up to 12% slower on PyPy. The limits page's floor is 37, where it was 45.

  • A float meets a Decimal bound as the Decimal it equals. Python compares a float with a Decimal exactly and through the thread's Decimal context, whose FloatOperation trap makes the comparison raise, and the walk read the raise as a refusal: under the trap Annotated[float, Ge(Decimal("0.25"))] refused 0.75, reporting greater_than_equal with "expected >= Decimal('0.25'), got 0.75", while outside it admits 0.75. The relations followed: Literal[0.75] was not_subset of it under the trap and subset outside. The walk, and the relations' ordering and reading of two bounds, compare the float as Decimal.from_float makes it, exact and silent under the trap, so every answer is the one Python's exact comparison gives outside it, whatever the context. pydantic 2.14 admits 0.75 under the trap too; msgspec refuses a Decimal bound.

  • A predicate re-entering its validator raises RecursionError on CPython 3.12 and 3.13. A predicate that calls its own validator re-enters the walk with nothing between two calls that those interpreters check against the native stack: about 3 KiB a call beside one unit of a C-recursion limit of thousands, so the chain ended CPython 3.12.16 in a segmentation fault on every thread of 1 MiB or less under the default recursion limit, and on the main thread under a limit of 10,000. Before 3.14 the walk reads the thread's own stack bounds before it calls a predicate -- once a thread, through the stacker crate, as 3.14 reads them for its own check -- and with less than 32 KiB left raises RecursionError("Stack overflow (N kB of the thread's stack left)") instead of calling it, which 3.14 and later raise at the Python frame between two calls. It costs about 20 instructions a predicate on 3.12 and nothing on 3.14 and later. Not on musl, whose pthread_getattr_np reports the main thread's stack mapped so far, and where 3.15.2's own check also lets the chain end the process on a 128 KiB thread, and not for an __eq__ or isinstance hook that re-enters; a walk between two re-entries still needs the stack it uses, so deep values on a thread under 1 MiB keep the limits page's floor. A level refused on PyPy for PyPy's stack rather than the walk's bound is reported as "a value the thread's stack has room to walk" rather than as past the 384-level bound.

0.0.30 - 2026-11-19

A release of answers, with two additions and no node. A tuple or a record is read a component at a time where the set of the whole is past the build's bounds: a string of 584 code points or more beside a part only the set representation reads, such as the meet a translation writes for {"type": "integer", "minimum": 0}, left the product undecided, and the product holds a value where each part does and none where one part holds none. Over the 70,000 pairs each generation of a fuzzer draws, the relations give 969 answers more than 0.0.29 on the second generation, 40 on the first and 868 on the fourth, and lose none; the families of exact relations over lists, records, mappings, TypedDicts and recursions give 5,738 more and lose none. The JSON Schema test suite, corpus and containment studies, read through valgebra-jsonschema, move no count, and valgebra-vtjson's differential suite passes.

Against 0.0.29 built here from its tag, on CPython 3.11 through 3.15, every shape of the profiled wheels counts within 0.5% of 0.0.29's but three on 3.15: the explaining walk of a record 4.70% more, of a list 0.93% more and a deep JSON document 0.56% fewer, each of which an environment 4,096 bytes larger reads alike, so the move is where the allocator's heap starts and not the code. The instruction gate's ten decision workloads count from 0.11% fewer instructions to 0.38% more.

Added

  • A meet or a complement only the sets read holds a value a refutation stands on. tuple[Annotated[str, MaxLen(584)], M], for M the meet a translation of {"type": "integer", "minimum": 0} writes, is not_subset of nothing by ("", 0), and a record of the same two required fields is not_subset of {}, where both stayed undecided. A string of at most 584 code points is a table past the set representation's state bound, so the pair's set is refused whole, and the meet beside it is read alone, as a refinement is. A complement such as ~Annotated[int, Ge(0)] beside the same string is read the same way.

  • A product is read empty a component at a time. tuple[Annotated[str, MaxLen(584)], E], for E a meet only the set representation proves empty, such as M & (Annotated[int, Lt(0)] | Annotated[float, Lt(0)]), is subset of nothing and of every other validator, and is_empty reads it empty, where both stayed undecided; so is a record with such a required field. The pair's own set is refused for its string, and the empty meet beside it is read alone.

0.0.29 - 2026-11-18

A release of the user guide's addresses, with no change to an answer, a message or a code: every membership, relation, error and render is the one 0.0.28 gave.

Changed

  • The user guide's pages are named for their topics. A page's address is its section of the site and its topic, /guides/schema-language/ where it was /03-schema-language/, the release notes at /changelog/ and the API reference at /reference/api/. Every address the site has served answers still, with a page that sends the reader to the new one and keeps the anchor the link named where the browser runs scripts, so a link in the README of an earlier release keeps working.

0.0.28 - 2026-11-16

A release of speed, with no addition, no fix and no node. The walk reads the shapes a JSON Schema translation writes by each value's type -- the JSON values, alone, as a list's element, as a mapping's value and beside a keyword's guard; the numbers JSON Schema calls integer and number; a string under length bounds; and a record whose undeclared keys hold the JSON values, read by its keys -- where it walked each node of them, and composing two validators builds no copy of an operand whose indices do not move. Every answer is the one 0.0.27 gave: against PyPI's 0.0.27 the metamorphic gate moves no membership and loses or contradicts no decision. The one count a caller can see move is a predicate's: validate explaining a refused record whose catch-all clause reads values runs a predicate on a field before the refusal once, where it ran twice. The algebra page states what == promises a decision: what one proves of a validator holds of every validator equal to it, and two equal validators never answer contrary, though past a query's bound one may decline where the other decides.

Changed

  • A tree of scalars is read by each value's type. A recursive definition whose union holds only scalar 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] -- asks each value's exact type once, where the walk spent a reference, its pair on the trail, the union's level and a branch per member around the same question. Outside the definition, list[J] and dict[str, J] -- J the definition, which a JSON Schema translation meets every array and object with -- read each value the same way, the bounds asked once for the container. Where a meet remembers what it walked, as one of list[J] and a list of records reaching J does, the scalars are read by type and the containers walked and kept. A value of no exact builtin type, one near either bound and one inside itself are walked as before, and a walk that explains reads the definition the general way.

  • A leaf is decided by a value's type and its number. A union, meet or complement of scalar kinds and of refinements of int and float by bounds and steps -- JSON Schema's integer, (int | Annotated[float, MultipleOf(1)]) & ~bool, and number -- is specialized to each exact builtin type when the validator is built, so a list of one, a mapping of str keys to one and a JSON array of one read each element's type and, where the type leaves it open, its number. A float under order bounds alone is two comparisons against the interval they admit. An int past a machine word the leaf reads, and a subclass, are walked.

  • A leaf may hold the JSON values. A union, meet or complement of leaves beside a reference to a tree of scalars, such as (~int | Annotated[int, Ge(0)]) & J with J the JSON values -- the guard a JSON Schema translation writes for a keyword with no type beside it, and for every not, if and then -- answers a scalar by the tree's leaves, and a list or a dict is walked as before.

  • A list of strings under length bounds is read against one range. list[Annotated[str, MinLen(m), MaxLen(n)]] folds its bounds into one range of code points, read once for the list, and compares each exact str's length with it. A meet of str and its length refinements, str & Annotated[str, MaxLen(n)] & Annotated[str, MinLen(m)] as a JSON Schema translation writes minLength beside maxLength, is the same range, whatever else the validator holds.

  • A record whose catch-all clause reads values is read by its keys. A record that admits an undeclared key by its value, {id: int, str: J} -- what a translation writes where additionalProperties is absent -- probes its declared fields as a TypedDict does, and scans the keys it does not declare alone. When validate explains a refused value it resumes where the first pass stopped, so a predicate on a field before the refusal runs once where it ran twice (docs/guides/refinements.md).

  • Composing a validator copies no operand whose indices do not move. The first operand of a combination, and one whose definitions the table holds at its start, enters as the handle it holds: a record nested sixty deep, each level met with the JSON values, composes in about half the time, and a relation between two built validators, which composes the two, counts 17% to 18% fewer instructions.

0.0.27 - 2026-11-14

A release of fixes, with no addition and no node. Five readings 0.0.26 answered wrong or paid too much for are repaired: a question asked inside a recursive builder stops at its placeholder rather than refusing the value, a subject of finitely many values is not refuted on a value the walk stopped on, a subject of one long value is built in time linear in its items and past 4,096 not at all, an undecided relation over a recursive subject builds one copy of a body for each definition, and two validators each below the other are equivalent. Over the 60,000 pairs each generation of a fuzzer draws, the relations give 0.0.26's answers and lose none, with one is_equivalent more on the second. Against PyPI's 0.0.26 the metamorphic gate moves no membership and loses or contradicts no decision, and the companions' suites and studies read no difference.

Against 0.0.26 built here from its tag, on CPython 3.15, the instruction gate's 44 workloads count from 0.07% fewer instructions to 0.16% more, and the profiled wheel's seven shapes count alike. On the profiled wheels of CPython 3.11 through 3.15 every shape counts within 0.7% of 0.0.26's but one: a relation between two built validators counts 2.6% to 3.1% fewer, the deciders and the reading by values sharing one oracle where 0.0.26 built a second for the reading. On the free-threaded 3.14 and 3.15 a shape of a few thousand instructions counts 3% to 46% apart from one build to another, either way, the count 0.0.26's section names as not repeating; the shapes past that count within 3%.

Read on the wheels PyPI serves, two environments of each release on each of CPython 3.11 through 3.15, on an AMD Ryzen 7 PRO 7840U under WSL2, every shape counts within 2% of 0.0.26's instructions but one: a relation between two built validators counts 2.6% to 3.2% fewer, the one oracle named above, and takes 6% to 10% less time on 3.11, 3.12, 3.13 and 3.15. Fifteen shapes moved by 5% or more at the instructions 0.0.26's wheel counts, which is where each build placed its loop, and none is charged to a change. Slower: on 3.15 list[bool] 31%, list[float] 19%, list[str] 16% and list[int | str] 13%; on 3.12 list[int | None] 5%. Faster: on 3.15 list[None] 39%, ten thousand integers 26% and the list nested twenty-five deep 9% to 10%; on 3.13 list[None] and list[bool] 17% and a record 5% to 6%; on 3.12 list[None] 15%, list[int | str] 9% to 10% and the JSON values' parsed document 8%; on 3.14 list[int | None] 6% to 7%.

Fixed

  • A question asked inside a recursive builder proves nothing about its placeholder. The placeholder stands for a definition not built yet, and a walk that meets it stops with unresolved_recursion rather than refusing the value, so every decider that reads a walk declines there. Inside the builder of recursive(lambda t: union(int, [t])), Literal[1] was not_subset of t and subset of complement(t), and the meet of a non-empty list[Literal[1]] with list[t] was proved empty, while the finished set holds 1 and [1]; each is undecided or not proved. complement(t).is_valid(1) is False there, since a stop refuses a value from a set and from its complement alike.

  • A subject of finitely many values is not refuted on a value the walk stopped on. The relation read value by value took a walk that stopped at the depth bound as a refusal and answered not_subset: 1 under twenty one-item tuples against a fixpoint whose body admits every such nesting, where each level spends a dozen meets of the walk's depth. Each value is asked in three answers, so the pair is undecided; a value refused still refutes.

  • A subject of one long value is built in time linear in its items, and past 4,096 not at all. A sequence of one exact length, list[Literal[1]] met with MinLen(n) and MaxLen(n), was built before its length was read: n = 2**62 raised a PanicException out of relation_to, which except Exception does not catch, a length near 3 * 10**17 aborted the process, and 10**5 items took 18 s, each item copying the row before it. A value of more than 4,096 items or fields is left to the deciders before anything is built, and one within it is built an item at a time: 4,096 items are refuted in milliseconds.

  • A relation the deciders leave undecided over a recursive subject keeps its memory. The subject unfolded twice copied its definition's body at every reference, so a body naming its definition m times built m copies of m copies before the set representation refused it unread: prefixItems of forty self-references against uniqueItems, as valgebra-jsonschema compiles them, took 14.5 s and 1.6 GB on 0.0.26 and could abort the process under a memory limit, and a fixpoint of 32,768 keys against a predicate took 23 s. One copy of a body is built for each definition, unfoldings left and polarity, and every reference holds it, and two handles of one node compare equal without being read: 19 ms and 40 MB, and 12 ms, where 0.0.25 took 86 ms and 7 ms. Every answer is the one it was.

  • Two validators are equivalent where each is below the other. is_equivalent asked both directions on one budget with the rules and the sets alone, so it could answer False where relation_to proved "subset" both ways: an empty tuple of nested lists against tuple[()], which the relation reads by its one value, and two translations from JSON Schema of the non-numbers, which a reading past the rules decides. It asks the two inclusions relation_to asks, each on a budget of its own.

0.0.26 - 2026-11-13

A release of answers, with eight additions and no node. Each reads a pair 0.0.25 left undecided: a meet of sequences read as the one sequence of its items' meet, a set holding a value refuted below a complement it lies inside, a declined pair split on a set its supertype negates and each half asked of its parts, a subject of finitely many constants related by each of its values, a recursive subject narrowed through two unfoldings, and an integer bound held past 64 bits. Three fixes bound what a report builds over a long key or long text. Over the 60,000 pairs each generation of a fuzzer draws, the relations give 117 answers more than 0.0.25 on the second and 22 more on the first, and lose none. The JSON Schema containment suite, read through valgebra-jsonschema, proves 200 more of its labeled inclusions and refutes 13 more, with no proof against a label; each of the 11 more refutations against a label is a wrong label the jsonschema package admits a witness against.

Against 0.0.25 built here from its tag, on CPython 3.15, the instruction gate's 44 workloads count from 0.07% fewer instructions to 0.35% more, each within its ceiling. On the profiled wheels of CPython 3.11 through 3.15 every shape counts within 0.5% of 0.0.25's but two. A relation between two built validators counts 3.7% to 4.2% more, 79 instructions a call on 3.15, for the relation by values a subject of finitely many constants gets where both deciders decline; the call's entry was read out of line and the count did not move, the profiled build placing the decider apart. The explaining walk of a scalar counts 0.4% to 0.5% more, 1.4% on 3.11, where a summary renders long text from its head and a report shares a key's string across its failures. The JSON shapes that count otherwise do so at one size of the environment and not at the other, which is an allocator's, but a union of records on 3.13, which counts 2.2% fewer at both. On the free-threaded 3.14 and 3.15 a count of a shape of a few thousand instructions does not repeat from one build to another: two builds whose walks count alike on every interpreter with the GIL read different shapes higher in each of three counts, the explaining walk of a scalar by 0.6% to 3.0% in one and a literal by 11% to 49% in the other.

Read on the wheels PyPI serves, two environments of each release on each of CPython 3.11 through 3.15, on an AMD Ryzen 7 PRO 7840U under WSL2, every shape counts within 2% of 0.0.25's instructions but one: a relation between two built validators counts 3.7% to 3.9% more, the relation by values named above, and takes 5% to 10% more time on each interpreter. A JSON document refused by list[int] counts 5.2% more on 3.12 at one size of the environment, which is an allocator's. Twenty shapes moved by 5% or more at the instructions 0.0.25's wheel counts, which is where each build placed its loop, and none is charged to a change. Slower: on 3.15 ten thousand integers 36%, list[None] 24%, list[str] 18% and the list nested twenty-five deep 7% to 11%; on 3.14 list[None] 31% and list[int | None] 7%; on 3.13 list[bool] and list[None] 20%; on 3.12 list[int | str] 10%; on 3.11 a JSON array of int | str | None 7% to 8%. Faster: on 3.15 list[bool] 23%, list[int | str] 17% and {str: int, int: bool} 7%; on 3.14 list[float] 15% to 16%, list[str] 14% and {str: int, int: bool} 5%; on 3.13 list[float] 12%, list[int | str] 8% to 9% and the JSON array 5% to 6%; on 3.12 list[int | None] 5%.

Added

  • A relation from finitely many constants reads each value. A subject built from literals, None, bool, fixed sequences, sequences of one exact length, closed records and unions of them, holding at most sixty-four values, is related by the membership of each where both deciders decline: the nested one-item list [[[["1"]]]] a translation from JSON Schema writes is not_subset of list[list[list[list[int | float]]]], where it stayed undecided. A supertype holding a predicate, a class or an attribute is not read this way. 47 of valgebra-jsonschema's undecided containment questions are decided by it, none against a label.

  • An integer bound past 64 bits is held up to 2**120. Annotated[int, Le(9223372036854776000)], the largest int64 as JavaScript prints it, is subset of Annotated[int, Le(18446744073709551615)] and the converse not_subset, where both stayed undecided: a bound is read within 2**120 of zero, a Python int past the 64-bit range among them. Past 2**120 a bound still declines, and a constant, a key and a step are still read within 64 bits.

  • A recursive subject is narrowed twice where once found no value. Where every reading left a relation undecided and its subject holds a reference, the subject is unfolded twice before the cut, and a value of its difference with the supertype refutes: the JSON values are not_subset of union(complement(list), Annotated[list, MaxLen(2)]) met with them, on [1, 1, 1], where it stayed undecided. A decided pair pays one comparison for it.

  • A split's halves are asked of their parts. Where every set the supertype negates leaves its halves undecided by the rules and the set representation, each half is asked of its parts, a union supertype narrowed to the branches it meets, with no split below: J the JSON value is not_subset of union(R("a"), intersection(J, complement(R("b")))), R(w) the closed record {"ref": Literal[w]}, where it stayed undecided. It refutes 9 of valgebra-jsonschema's undecided containment questions, each a label its results page shows wrong, and loses none.

  • A pair the deciders declined is split on a set its supertype negates. U <= T is asked as U & C <= T and U & ~C <= T, for a C the supertype holds under a complement, so J the JSON value is subset of union(Literal[2], intersection(J, complement(Literal[2]))), where it stayed undecided: the excluded middle valgebra-jsonschema writes for anyOf [Y, not Y], which decides 182 of its containment suite's undecided questions, none against a label. A refuted half refutes the pair.

  • A set inside c that holds a value is refuted below the complement of c. For J the JSON value and rec a record of a named field and a pattern-keyed clause over J, {"foo": Literal[1], "vroom": Literal[2]} is not_subset of complement(intersection(rec, J)), where it stayed undecided: it lies inside rec, by a proof past the structural rules, and holds a value. It is the pair valgebra-jsonschema asks for a constant below not, and 44 of its containment suite's undecided questions are decided by it.

  • A meet of sequences is read as the one sequence of its items' meet. intersection(list[J], union([], list[str]), Annotated[list[Any], MinLen(1)]), for J the JSON value, is not_subset of intersection(list[J], union([], list[rec])) for a record rec with a required key, on ["x"], where it stayed undecided. It is how valgebra-jsonschema writes minItems beside the items, and the tuple form is read alike. It is read so wherever it stands, as a record's field, a list's items or a mapping's values: intersection(dict[str, J], {"a?": intersection(list[J], union([], list[str]), Annotated[list[Any], MaxLen(5)])}), a closed object with a bounded array property as the companion writes it, is subset of {"a?": Annotated[list[str], MaxLen(5)]}, and the same object under MaxLen(6) is not_subset of it, on six words, where both stayed undecided.

  • Every sequence of a meet is read at once. For J the JSON value and rec the record intersection(dict[str, J], {"t": str}), intersection(list[str], Annotated[list[Any], MinLen(1)], list[rec]) is subset of nothing, where it stayed undecided: each pair of its members holds a value, and the three hold none. It is the shape valgebra-jsonschema writes for minItems beside two item types.

Fixed

  • A long key is cut where a message writes its location. A string key past eighty characters is written in str(error) and in each item's message as a subscript of its first eighty, ['kkk...], and the path keeps it whole. A JSON document holding one key of a hundred thousand characters over a thousand failures built a 100 MB message at the raise.

  • The failures under one key share its string in errors. Each item's path names the key whole, and the items under one mapping entry hold one str for it rather than a copy each, so errors grows with the failures and not with their product with the key's length.

  • Long text is rendered from its head in a value summary. A str, bytes or bytearray past eighty items is rendered from its first seventy-nine, which reach the summary's eighty characters, rather than rendered whole and cut: a 10 MB string held a thousand times in a failing list took 17 s to report. The summary is the same but for its quote, which repr picks from the head alone where a single quote lies past it.

0.0.25 - 2026-11-09

A release of answers, with thirty-three additions and no node. Thirty-one of them read a pair 0.0.24 left undecided, from a meet of a kind with members of that kind and a bound written over every value read within the rest of its meet to a mapping's clauses beside a table, and two build what 0.0.24 refused: a class reached again through a type alias, and that bound met with str as a map key. Over the 60,000 pairs each generation of a fuzzer draws, the relations give 1,766 answers more than 0.0.24 on the second and 698 more on the first, and the JSON Schema containment suite, read through valgebra-jsonschema, proves 107 more of its labeled inclusions and refutes 145 more, with no proof against a label. One answer 0.0.24 gave on those pairs reads undecided: the law A <= (A & ~B) | (A & B) over a union of float refinements met with the JSON values, which 0.0.24 proved by not reading that a float refinement holds a value, and which the query's budget does not reach once it does. Seven entries are security fixes, and their advisories go out with the release.

Against 0.0.24 built here from its tag, on CPython 3.15, the instruction gate's workloads count from 78.31% fewer instructions, a list of refined elements, to 1.01% more, a map keyed by a language, each within its ceiling, and the whole steps asked of the sets count 10.54% fewer. The profiled wheel counts the one int 11.91% fewer, a wide record 7.57%, the error report 4.18% and the JSON document 1.73%, and the build 0.25% more. On the profiled wheels of CPython 3.11 through 3.15 a validator of one scalar kind is its type test and counts 19% to 22% fewer, for a load and a comparison every other call pays at its entry: two instructions, union 0.7% to 0.9% and literal 0.4% to 0.5%. A list of refined scalars counts 66% to 75% fewer. A mapping counts twenty instructions more a call, 0.2%, where a list of records reads its node once and counts 4.7% fewer, and a relation between two built validators 0.2% to 0.4% more. A list nested twenty-five deep counts 0.62% more on 3.13 alone, and reads 3.0% fewer cycles. The JSON shapes that count higher do so at one size of the environment and not at the other, which is an allocator's. On the free-threaded 3.14 and 3.15 a count of a shape of a few thousand instructions does not repeat, and the two that read higher twice, a relation and a mapping, read within 2% in cycles. A refusal reported over a value nested twenty thousand deep counts 69% fewer instructions and takes 24 us where 0.0.24 takes 64 on CPython 3.15: a union counts how far its branches went only between two that went past its location, and moves the branch it reports where 0.0.24 copied it at every level.

One cost is named. A relation the set representation declines reads more before it declines: of the 840,000 calls the fuzzer's second generation asks, on profiled CPython 3.14 wheels built here, 295 take five times 0.0.24's time or more and 5 ms or more, up to 45 ms, nearly all a decline 0.0.24 also gave, and the generation takes 24% more time in all where the first takes 14% less; that time is spent in the readings the additions name.

Read on the wheels PyPI serves, two environments of each release on each of CPython 3.11 through 3.15, on an AMD Ryzen 7 PRO 7840U under WSL2, the shapes that count fewer instructions take less time in both: a list of refined scalars 41% to 73%, building a union 68%, one scalar 18% to 23% on 3.12 through 3.15, a membership test 17% to 24%, refined fields 14% to 19% and a list of records 7% to 11%. Twenty-one shapes moved by 5% or more at the instructions 0.0.24's wheel counts, within 0.6%, which is where each build placed its loop, and none is charged to a change. Slower: on 3.15 list[bool] 31%, {str: int, int: bool} 9% and list[int | str] 8%; on 3.14 list[str] 16%; on 3.13 list[float] 11%, list[int | str] 10% and a list nested twenty-five deep 7%; on 3.12 list[None] 17%; on 3.11 list[float] 16%, the list nested twenty-five deep 6% and list[int] refusing a JSON document 6%. Faster: on 3.15 list[str] 15%, list[None] 20% and ten thousand integers 26%; on 3.14 list[None] 24%, list[int | None] 12% and a relation between two lists 9%; on 3.12 list[float] 12% and list[int | str] 9%; on 3.11 list[bool] 10% and list[int | str] 9%.

Added

  • A length or a pattern written over every value and met with str is a map key. {intersection(str, Annotated[object, MinLen(2)]): int} builds and keys the words of two characters or more, as {Annotated[str, MinLen(2)]: int} does, the two maps subset of each other both ways, where the key was refused as narrowing the keys it governs. Its complement met with str builds too. Alone, or met with a union such as str | bytes whose other kind it narrows, the bound stays refused, and so does an order bound met with int.

  • A bound written over every value and met with a base is that bound over the base. intersection(str, Annotated[object, MinLen(2)]) and Annotated[str, MinLen(2)] are subset of each other both ways, and so are the same length met with bytes, a list or a tuple, its complement met with str, and intersection(int, Annotated[object, Gt(0)]) with Annotated[int, Gt(0)], where the meet read undecided. Met with a set or a dict, whose lengths the set representation does not count, it stays undecided.

  • A union holds a value whichever member its constants list first. A record whose field is intersection(X, B) | intersection(X, complement(B)) is not_subset of nothing on a value of X & B, where it read undecided when the other branch came first.

  • Zero is a multiple of an exact Fraction or Decimal step. Annotated[int, MultipleOf(Decimal("2.5"))] and Annotated[int, MultipleOf(Fraction(1, 3))] are not_subset of nothing and of str on 0, where they stayed undecided.

  • A meet of a kind with members of that kind is read as those members. intersection(int, Annotated[int, MultipleOf(0.5)]) is not_subset of nothing on 0, as the refinement alone is, where the meet stayed undecided.

  • A class reached again inside a type alias is tied by the alias. Box[Tree], with type Tree = int | Box[Tree], builds the boxes holding a tree, and a dataclass naming itself through type Rest = Node | None is checked in depth, where each was refused as a class reached again while its own fields are being built. A class naming itself with no alias between is refused, since nothing ties that cycle.

  • A word's length range is outside a table holding fewer constants. Annotated[str, MinLen(1), MaxLen(1000)] is not_subset of Literal["a"], on "b", where it stayed undecided past a MaxLen of 512.

  • A pair asked through a complement is read by the parts it turns to. For B = union(Annotated[int, Ge(2)], Annotated[int, Le(3)], Annotated[dict, MaxLen(2)]), which int is subset of, complement(B) is subset of complement(int) and intersection(int, complement(B)) of nothing, where each stayed undecided.

  • A supertype's clause of constants its subject never spells is beside it. dict[Annotated[str, Regex("c")], str] is subset of {"c?": int | None | str, Literal["a"]: bytes}, where it stayed undecided.

  • A mapping of words under a length counting each is their record. Annotated[dict[Literal["a"], int], MinLen(1)] is subset of {"a": int} and not_subset of nothing, and Annotated[dict[Literal["a", "b"], int], MinLen(2)] is subset of {"a": int, "b": int}, where each stayed undecided.

  • A meet supertype and a union subject are read a member at a time. list[int] is not_subset of intersection(union(complement(list[J]), Annotated[list, MaxLen(2)]), J) for the JSON values J, on [1, 1, 1], and union(Annotated[str, Regex("a")], Annotated[float, MultipleOf(0.5)]) of Annotated[float, MultipleOf(0.5)], on "a", where each stayed undecided with a member refuted.

  • A clause's key split between clauses of a supertype is covered. dict[Literal["a"] | P, int] is subset of {Literal["a"]: int, P: int} for P = Annotated[str, Regex("b")], so a record's close() is related back to it, and Validator(dict[object, S]).open() of Validator(dict[str, S]).open(), where each stayed undecided.

  • A clause whose key holds no value and an optional field holding none carry no entry. dict[intersection(Literal["a"], Literal["b"]), int] and dict[intersection(str, int), int] are subset of {}, and {"a?": Never} of dict[Color, bool], where they stayed undecided: each holds the empty dict alone.

  • A field's name is read as a word of a clause narrowed by a language. {"a": int} is subset of recursive(lambda t: union(int, {Annotated[str, MaxLen(1)]: t})), as of one such mapping, where a reference in the way left it undecided.

  • The complement of a table holds a plain value of a kind it has no constant of. complement(Literal[Color.RED]) is not_subset of str, on None, and of union(str, int), where each stayed undecided.

  • Two attribute records share no value where a shared attribute holds none. A protocol with x: Literal[Color.RED] is subset of the complement of one with x: Literal[Color.GREEN], where it stayed undecided, as two records requiring one key already read.

  • A meet of refinements of one base is read as the one they are. intersection(Annotated[dict, MaxLen(2)], Annotated[dict, MinLen(2), MaxLen(3)]) is not_subset of nothing, intersection(Annotated[int, Le(5)], Annotated[int, Ge(5)]) of Annotated[dict, MinLen(3), MaxLen(5)], and a list of a refinement of a union whose branches are refinements of nothing, where each stayed undecided.

  • A mapping's clauses are read beside a table and over a language of keys. Validator({Literal["a"]: str}).open() is not_subset of the same over bool, on {"a": "s"}, a recursion over Annotated[str, Regex("a|b")] keys of one over Regex("a"), on {"b": 1}, and {"b": str} is subset of {complement(Literal["a"]): anything}, where each stayed undecided.

  • A class holds no boolean but through the order of bool. bool takes no subclass, so intersection(K, bool) is empty and subset of nothing for a class with a plain metaclass, where it read False and undecided.

  • A float refinement and a float step over the integers hold a value. Annotated[set[Annotated[float, Ge(0)]], MinLen(1)] and Annotated[int, MultipleOf(0.5)] are not_subset of nothing, where they stayed undecided.

  • A plain value of a kind is outside a table of another exact type. list[str], bool and Annotated[int, Ge(2)] are not_subset of Literal[Color.RED], and bool of Literal[2**63], where they stayed undecided. A literal pins its constant's type.

  • Two sequences meet in nothing at a position each of their values has. [int, None] is subset of the complement of recursive(lambda t: list[t]), and intersection([int, None], R) is empty, where the first stayed undecided and the second read False. A length bound names those positions: Annotated[list[int], MinLen(1)] is subset of that complement, and of the complement of list[str].

  • A position or a clause holding no value is read as what it leaves. list[N], for an N with no finite value such as recursive(lambda t: tuple[t]), is subset of Annotated[list[int], MaxLen(0)], and dict[str, N] of {}, where they stayed undecided.

  • A mapping's own lengths refuse a length its subject holds. Annotated[dict, MaxLen(2)], Annotated[dict, MinLen(1)] and Annotated[dict[str, int], MinLen(1)] are not_subset of {}, on a dict of one key, where they stayed undecided.

  • A set's own lengths refuse a length its subject holds. set[Literal[1, 2]] is not_subset of set[Literal[1]] | set[Literal[2]], on {1, 2}, where it stayed undecided, in a millisecond at 256 members against seventeen.

  • A set of one member and a mapping of its required fields hold a value. Annotated[set[tuple[int]], MinLen(1)], Annotated[{"a": int}, Len(1, 1)] and Annotated[dict[bool, int], MaxLen(1)] are not_subset of nothing, where they stayed undecided, and Annotated[{"a?": int}, MinLen(0)] of {"a": int}, on {}.

  • A refinement only the sets read holds a value a refutation stands on. recursive(lambda t: union(Annotated[str, Regex("a")], tuple[t])) is not_subset of str, by ("a",), where it stayed undecided.

  • The complement of a set proved empty is every value. complement(S) for an S is_empty proves empty relates as anything does, where it read for up to a few seconds and stayed undecided.

  • A meet is read as a member below all the others. Where the pair declined everything else, A & B answers as A wherever A is proved below B. Color & (str | Color) is not_subset of a protocol its members do not carry, a true refutation lost in 0.0.23, and a list of an enumeration met with the class's complement reads as the list.

  • A table of constants beside what holds them is the table. intersection(str, Literal["a", "b"]) answers as Literal["a", "b"] does, the spelling a translation of an enum of strings writes. A relation between two of 60 and 400 words read 79 ms on 0.0.24 and 3.5 ms on 0.0.23, for an answer it reads in 1.6 ms, and a thousand drawn pairs that stayed undecided decide.

  • A supertype proved empty is the bottom. A schema is_empty proves holds no value, so what is below it is what is below nothing: str is not_subset of a protocol whose y is itself, where it stayed undecided. A relation of int against a recursive attribute record with no value read for up to 9.7 s on 0.0.23 and answers at once.

  • A leaf is decided beside what stops the pair. A pattern below a pattern, a bool below a bound over int, and every other pair only the sets read, stayed undecided beside a recursion, a class key or a third attribute record, since the pair's own reading stopped there: tuple[bool, R] below tuple[Annotated[int, Lt(8)], R], and {"a": P, "b": J} below the same record over a wider pattern, the object a JSON Schema writes most. A pair everything else declined asks the sets of each goal the rules decline with no reference in it.

  • A sequence or a mapping is refuted below a union on a value of one item. list[bytes] is not_subset of J | list[J], the shape of a field holding a document or a list of them, on [b""], and list[bool] of list[list[dict]] | list[list[dict[str, int]]] on [True], a pair 0.0.24 lost and 0.0.23 answered. Each branch holds [], so none drops out of the union, and no set is built.

Changed

  • A note in 0.0.24 was wrong: it lost answers it gave. Its section says of a relation's reading that "No answer it gave moves." Four pairs 0.0.23 decided read undecided on 0.0.24, among them list[bool] below list[list[dict]] | list[list[dict[str, int]]], a list of an item outside every branch. The note stands where it was published, and this release decides all four again.

Security

  • The module loads in the main interpreter of a process, once. A legacy subinterpreter, which is what mod_wsgi runs an application group in, loaded it, and every interpreter after the first to build read that one's typing: Validator(Annotated[str, Regex("a")]) built as str and admitted "b", and Validator(Any) refused every value. The pattern was dropped so on 0.0.17 through 0.0.24, every published wheel read on CPython 3.12. An embedder calling Py_Initialize again after Py_FinalizeEx ended the process in the next build, read on 0.0.24. Both raise ImportError at import valgebra; the main interpreter loads it whichever imports first.

  • Each key of a parsed object is its own value to the walk's memo. is_valid_json answered one key of an object with the answer kept for another, where two members of a schema read a recursive key language: {K: int, complement(K): str}, for K = recursive(lambda k: union(Annotated[str, Regex("b+")], [k])), admitted {"b": 0, "0": 0} and refused {"b": 0, "0": "x"}, against is_valid of json.loads and against validate_json on the same text. The answer was wrong on 0.0.19 through 0.0.24, every published wheel read, on CPython and PyPy alike. The memo keys a string by its text.

  • What a relation over a float's bound or a step assumes of a subclass is stated. A step met with bounds is proved empty over the builtin's residues, and a subclass with a % of its own is admitted by it, and np.float64 compares an integer past 2**53 rounded where the bound is read exactly. Both answers stay, inside the assumption the soundness page names, and known-unsound tests pin them.

  • A proof between a record and a mapping narrowed by a language names what it assumes. dict[Annotated[str, Regex("a")], int] is subset of {"a?": int}, and {"a": int} of that mapping, on 0.0.24 as here. A str subclass with a __hash__ or __eq__ of its own stands against each: a key of the text a no lookup of the name finds, and a key equal to the name holding another text. The answers stay, since refusing them gives up every proof between properties and patternProperties, over keys JSON gives none of these for; the soundness page states the assumption, and known-unsound tests pin both cases.

  • A dict's entries are read from its storage on PyPy. PyPy's PyDict_Next answers each value with a lookup of its key, so a dict holding two keys that reach one name through a slot a deleted key left read one value for both, and {str: int} admitted {Plain("a"): "s", Folded("A"): 1}, which CPython refuses on "s". The answer was wrong on every PyPy wheel, 0.0.1 through 0.0.24. The scan reads dict.items.

  • A required field is paid for by the entry its name finds. A dict can hold two keys that reach one name, since str's == and a subclass's own need not agree: with Plain a str subclass and Folded one comparing by its folded case, {Plain("a"): 1, Folded("A"): 2} has no key b, and {"a": int, "b": int, str: int} admitted it, as {"a": int, "b": nothing, bytes: int} did while proved empty. The answer was wrong on 0.0.19 through 0.0.24, every published wheel read. Every reading of a record reads a name as the dict answers it, and the other entry as a key no field declares, so {"a": int, str: str} admits {Plain("a"): 1, Folded("A"): "s"}, and {"a": object} refuses a dict holding both keys by naming the extra key, where it named a mutation of a value nothing moved.

  • np.float64 is a float to the relations, as it is to the walk. intersection(np.float64, float).is_empty() was True, with np.float64(1.0) in both; np.float64 was subset of complement(float) and not_subset of float, and a subclass of float was proved disjoint from it beside a class deriving from both. The answers were wrong in 0.0.23 and 0.0.24. Its __base__ is floating, so a reading along the chain found no builtin. A class with none there takes its kind from a builtin its order names, which CPython refuses an mro() to add.

Fixed

  • Two equal Fraction or Decimal constants built apart are one. Two validators of Annotated[int, MultipleOf(Decimal("0.7"))], each built with its own Decimal, relate subset both ways and are equivalent, where they compared == and read undecided.

  • A pattern holding a lone surrogate is refused by its surrogate. Annotated[str, Regex("\ud800")] was refused with "a pattern is matched against text, so write the pattern as a str", which it is. The message names the lone surrogate, a code point no UTF-8 text holds, which the pattern engine reads alone.

  • A refined record or list display prints as the validator it builds. repr of Validator(Annotated[Validator({"a": int}), MinLen(1)]) was Annotated[{'a': int}, MinLen(1)], which Python 3.11's typing refuses to read back ('dict' object has no attribute '__module__') where 3.12 reads it. It prints Annotated[Validator({'a': int}), MinLen(1)], which reads back as the same schema on every interpreter, and so does a fixed list.

  • An annotation folds a recursion and its complement as its combinator does. For a recursive K, intersection(complement(K), K) is nothing and union(complement(K), K) is anything, and Annotated[complement(K), Validator(K)] and Union[complement(K), K] stood as written: the complement law reads a recursion through its definition, which the annotation's build held and did not pass. Each spelling of one meet or one join compares equal.

  • A class applied past its type parameters is refused. For a NamedTuple declaring no parameter, Point[str] is an alias tuple's own subscription makes, and its validator was Point's, dropping the argument: Validator(Point[str]) == Validator(Point). It raises NotImplementedError naming the count, as an alias applied past its parameters does.

  • A recursion with an arm narrowed past words is refused as a map key. dict[recursive(lambda t: union(Annotated[int, Ge(0)], tuple[t, ...])), int] built, where a key narrowed by a number's bound is refused where it is written, and its map's relations declined where the key partition decides them: dict[int, int] against it read undecided, which {-1: 1} refutes. It raises NotImplementedError, as dict[Annotated[int, Ge(0)], int] does.

  • A signal from an element's repr raises out of the message. Validator(int).validate([x]), for an x whose __repr__ raises MemoryError or RecursionError, reported [<X instance at 0x...>] on 0.0.24, since reprlib, which renders a container, reads every Exception as an element that cannot render; the two signals raise, as they do from the value's own __repr__. An element whose __repr__ raises an ordinary exception prints as <unrepresentable>, the word for a value whose __repr__ raises, with no address. A validator's repr raises MemoryError where Python cannot give a field name's or a pattern's text room, where it printed Rust's spelling of the text.

  • A key past the digit limit is its hexadecimal text in a path. Validator(dict[str, int]).validate({10**5000: 1}) refuses the key, and on 0.0.24 its path held the key as an int, which json.dumps(err.errors) and repr(err.errors) refuse past the interpreter's limit on the decimal digits it converts. The path holds the key's hexadecimal text, '0x31e2...', as the message writes it; the text indexes nothing, and no JSON document holds such a key.

  • A failure inside a key ends its path at the key. dict[tuple[int, ...], list[int]] refuses {("x",): ["y"]} at position 0 of the key and at position 0 of its value, and on 0.0.24 both items held the path ("('x',)", 0), a place in the value. The key's item ends at the key, ("('x',)",), since no subscript reaches into a key, and its message names the place in it: at ('x',), key[0]: expected int, got 'x' [int_type].

  • An allocation Python refuses inside a call raises MemoryError. Where the interpreter could not give memory to an object valgebra builds -- a schema's, a report's, a parsed document's, a relation's answer, a rendering, an error's attributes -- the call raised PanicException, a BaseException that neither except MemoryError nor except Exception catches, and ended the process where even that exception could not be built.

  • What a marker or a class yields is read within the node bound. A grouped marker whose constraints never end was read until memory ended and the process aborted, with no Python exception, and so were a protocol's members and a named tuple's _fields given an iterable that does not end; a TypedDict whose __required_keys__ never ends never returned. Each raises ValueError: schema is too large past 100,000 items.

  • A value sharing a sub-object answers as its copy past the walk's bounds. The walk's memo answered a definition at a value from any earlier walk of it, and a walk with less of the bounds left, which would stop on its own, found the answer instead: against recursive(lambda t: union(int, list[t], list[union(t, str)])), a list sharing one inner list at two depths was False to is_valid and admitted by validate, and a member where the same value sharing nothing was refused with recursion_limit. A document reaches it too, where the second list branch reads an inner list again: [[..., "s"], "s"] a hundred deep was refused by is_valid_json and admitted by validate_json. An answer is found by a walk with as much of each bound left as the kept walk used.

  • A refusal names a refined branch's bounds and each clause reading a key. union(Annotated[int, Ge(10)], Annotated[int, Lt(0)]) read 5 as expected one of: int, int, and complement(Annotated[int, Ge(0)]) as expected not int, in a set holding -1. {Literal["a"]: int, str: str} refused {"a": 1.5} as string_type, naming one of the two clauses it read, and a key no clause held was refused for its value too. The first two read one of: int and >= 10, int and < 0 and not (int and >= 0), a key several clauses hold names each, one of: str, int, and a key none holds names the keys alone.

  • A refinement of a refinement and equal constants past 64 bits are one. typing flattens Annotated[Annotated[X, a], b], and a Validator between the two kept two nodes, so one set relates apart under two spellings and repr printed what did not read back. The two are one node, and two Literal[2**63] from two objects one constant, so union(lit(x), complement(lit(y))) folds to anything as it does for 5.

  • A pattern over a Unicode class beneath lists reads in under a second. A product of two automata counted as one step whatever it holds, so a \w* beneath four lists read 3.7 s before a bound declined the pair, where 0.0.22 declined at once. A build pays for a product by its table, and the pair answers in 0.5 s and is refuted, where it stayed undecided.

  • A named tuple holds the positions its class stores. _fields is an attribute any subclass can write, and platform.uname_result names a sixth, computed on demand, over five stored items, so Validator(platform.uname_result) refused platform.uname(), on every release read back to 0.0.20. The positions are those of the class directly above tuple.

  • A relation over a large step keeps to the memory it may have. A MultipleOf's table holds a list per residue, and an operation over it counted as one step of a build: two list bounds over a union of ranges beside a step of 4096, in about fifty nodes, read for over a minute, kept 6.4 GB, and under a limit on memory ended the interpreter with no exception, from 0.0.23 over integers and from 0.0.24 over floats. A build pays for a table by the residues and spans it holds, so such a pair declines within seconds, where a table under a thousand of them answers as it did.

0.0.24 - 2026-11-06

A release of value universes, with five additions and no node. What a format holds is a set of Python values, so JSON's and TOML's are written in the algebra as it stands, on a page of their own. The representation reads what such a set is made of: a whole step over floats, a key narrowed by a pattern or a length, a Fraction or Decimal bound over a float, and a meet of 112 ranges where six ended undecided. numpy's generic builds as a class met with a record, and the same spelling reads JAX's and PyTorch's arrays. PyPy wheels are built for PyPy 8.0 alone, on 3.11 and 3.12.

Against 0.0.23 built here from its tag, on CPython 3.15, the relations asked of the sets count 30.26% fewer instructions and the length bounds asked of them 66.52% fewer. The core workload, the other decision workloads and every binding shape count within 0.03%, and the profiled wheel counts what 0.0.23 counts, to the instruction. On the profiled wheels of CPython 3.11 through 3.15 the walk counts what 0.0.23 counts but where an allocator moves a shape that allocates, and the largest move that repeats at two sizes of the environment is 0.38%, a JSON document nested deep on 3.11, which reads 0.5% fewer cycles. On the free-threaded 3.14 and 3.15 a count of a shape of a few thousand instructions does not repeat, and the shapes that read higher twice read level in cycles, to 2.0% on a wide record, about the spread of one build read against itself.

PyPI's wheels for CPython on Linux x86_64, read in cycles against 0.0.23's at one count (release step 9, an AMD Ryzen 7 PRO 7840U), walk some lists at another speed, by where each build places a kind's loop. Slower: list[int | str] by 8% to 20% on 3.11, 3.12, 3.14 and 3.15, list[None] by 19% on 3.11 and 63% on 3.15, list[bool] by 12% on 3.11, and ten thousand distinct integers by 35% on 3.15, where a thousand read the same. Faster: list[float] by 12% on 3.13, and on 3.15 list[str] by 14%, list[float] by 15% and list[bool] by 24%. Every other shape reads within 5%.

Added

  • A Fraction or Decimal bound over a float is decided. It is read at the float on the side the bound keeps, as Python's exact comparison does, so Annotated[float, Ge(Decimal("0.1"))] is the set Annotated[float, Ge(0.1)] is, and Annotated[float, Ge(0.25)] is not_subset of Annotated[float, Ge(Decimal("0.5"))], where both were undecided.

  • A relation reads a wider schema. The set representation takes a schema of up to 1024 nodes, where it took 64: a range of JSON integers with 112 others taken out of it is decided, in 2.5 ms, where six made it undecided. A product is stopped by the work it spends, as it was, and a union's members are joined in rounds. A union of patterns reads their automata, so one of 300 proves its meet with a complement in about 100 ms where it declined in 13, and one of 512, past the bound, declines in about 110 ms where it took 14.

  • numpy's own generic builds. np.ndarray[S, np.dtype[T]] and npt.NDArray[T] denote the instances of np.ndarray whose shape is in S and whose elements are T's, by the kind and the width of the dtype, where both were refused. It adds no node: the class met with an attribute record, which the relations decide, so npt.NDArray[np.float64] and npt.NDArray[np.float32] share no value. An abstract scalar type is refused, and the elements are not read.

  • A map key narrowed by a pattern or a length. dict[Annotated[str, Regex("x-.*")], V] builds, where it was refused, and so do MinLen, MaxLen and the connectives over them, which name a regular language of str keys. Two clauses whose keys overlap read the join of their values on the keys they share, so a key takes one answer, and the relations read the languages: the map above is subset of dict[str, V] and the reverse not_subset. A key narrowed by a number's bound, a word's order or a callback stays refused.

  • A step over floats is decided as a set. x % n == 0 holds of the whole floats of one residue class, so the float component holds a list of intervals per residue beside the floats no step holds, and bounds and steps are read together: Annotated[float, MultipleOf(1), Gt(30), Lt(31)] is empty, Annotated[float, MultipleOf(1)] is not_subset of Annotated[float, MultipleOf(2)], and the complement of a range of JSON integers, an int that is no bool or a float that is a multiple of one, is decided. A step that is fractional or past 4096 is left to the rules.

Changed

  • A relation builds less to answer, and declines a little less. A set's complement is built only where it is read: what a list's element leaves, and what one set leaves of another, are read a kind at a time, so a kind a set misses costs nothing. The relations of the JSON Schema containment suite read 38% fewer instructions, and what a relation keeps of its allowance decides a few it left undecided. No answer it gave moves.

  • PyPy wheels are for PyPy 8.0, on 3.11 and 3.12, on manylinux. A wheel is published for each series on x86_64 and aarch64, and each runs the product suite on every push and in the release. PyPy 7.3 and PyPy on musl install from the source distribution, which needs a Rust toolchain: no push ran 7.3, and nothing here holds a musl PyPy to load a wheel. Free-threaded 3.14 runs on every push as well, and the release runs the product suite on the free-threaded musllinux wheels, which it built and never loaded.

Fixed

  • Importing the package loads less. It registers no valgebra._error_hooks module, and on PyPy an import loads neither importlib nor warnings.

0.0.23 - 2026-11-04

A release of decisions, with thirteen security fixes and a new floor: fifty additions, two changes, thirty-two fixes and thirteen security fixes. The relations answer where they answered undecided. A pair every decider declines is asked in its other spellings, and again under a larger allowance; a meet holding a complement is read as the relation it is; a union is narrowed by the complements beside it and decided a part at a time; lengths and kinds are read off the shapes that hold them; and a recursive reference refutes at any kind. Of 784,000 questions a drawn corpus asks, 33,995 ended undecided on 0.0.22 and 8,882 do here, and on 154,000 drawn seeds no answer 0.0.22 gave is lost or flipped.

Seven of the security fixes are proofs a value refutes: a literal of a class with an == of its own, two bounds compared where the walk reads an operand otherwise or over lists, a class whose metaclass hid its hooks, a class given __slots__ after it was made, and an enumeration with an instance past its members. Five are acceptances, a generic class reading a qualifier, a default or a list of types as a value and admitting what the class refuses. The last is a walk under a lowered recursion limit that ended the process on PyPy. Each names the releases it reached. Python 3.11 is the floor, and 3.10 leaves the matrix.

Against 0.0.22 built here from its tag, the relations asked of the sets count 48.66% fewer instructions, the length bounds asked of them 13.75% fewer and the core workload 0.75% fewer. On the profiled wheels of CPython 3.11 through 3.15 a scalar, a record, a list of records and a list nested twenty-five deep count what 0.0.22 counts, to the instruction, but where an allocator moves a shape that allocates. A union counts 0.34% to 0.60% more and a union of literals 0.17% to 0.61%, for the two tests that read a tagged union at its tag, where a thousand records read in 0.14 us against 48; a recursive schema counts 0.44% to 0.87% more and a list of refined integers 0.43% to 0.55%. A relation between two validators counts 4.2% to 4.4% more at its root, for the class scope a root build holds and the two maps a query keeps its readings in, and the decision workloads 0.25% to 1.97% more, the relation matrix the most, for the readings a pair the rules decline is asked. A question every decider declines can take longer to decline: a few drawn answers went from under 5 ms to as much as 65 ms, each unchanged, while five of the six drawn corpora take 8% to 63% less time in all. On the free-threaded 3.14 and 3.15 a mapping counts 23% to 27% fewer and a list of records 8%, and a list nested twenty-five deep about 1% more.

Added

  • A value of the difference cut the other way refutes at any kind. A recursive reference is cut once to read a relation, and the difference that proves an inclusion holds values the real one does not, so where it held one at a kind the cut reaches the answer was undecided. The pair is read again with the subject cut to nothing and the supertype to everything, a difference inside the real one, and a value of it refutes. A protocol whose x is recursive(lambda t: [t]) is not_subset of int, as recursive(lambda t: intersection(union( Validator([]), list[t]), complement(None))) is of str, on [], where each was undecided. The relations over no fixpoint read no more instructions; a corpus of purely recursive schemas read 8% more, and answered a quarter of what it left undecided.

  • A question undecided at an allowance is asked again with a larger one. A relation, an emptiness or an equivalence that ends undecided because a pair asked in its other spellings ran out of its 4,096 steps, while the question had steps of its own left, is asked once more with 65,536. A record a translation from JSON Schema guards to objects, its tag a number from 2**53 or any value but a number, is not_subset of a tree of whole numbers, on {"tag": "x"}, where it was undecided. The first asking's answer stands wherever it decides. A question that stays undecided is asked twice: the declines of a fuzzing corpus took 8% to 38% longer in total, the slowest of them about twice as long.

  • An enumeration met with sets refusing every member holds no value. A meet holding a class is read through the complement law: it is empty where the class is below the complement of the other members' meet, which the bindings ask of an enumeration a member at a time. For an enumeration Pair whose members carry no x and a protocol HasX requiring one, intersection(Pair, HasX) is subset of nothing and is_empty, as Pair <= ~HasX already was, where the meet was undecided.

  • A refinement of a union holds what its refined branches hold. A refinement of a union is the union of its branches refined, so it holds a value where a branch under its bounds does, and a branch so refined that holds a value of a kind the supertype holds none of refutes the pair on that value: Annotated[int | str, MaxLen(1)] is not_subset of int and of nothing, on "", and Annotated[str | bytes, MaxLen(256)] of bytes, where each was undecided.

  • A shape beside a length bound it misses holds no value. A meet of a record, a sequence or a set with a refinement whose length bounds that shape's lengths miss is empty, read as the shape under the bounds is: {"a?": int} & Annotated[dict, MinLen(2)] is subset of nothing, as Annotated[{"a?": int}, MinLen(2)] is, where the meet was undecided.

  • A mapping holds no more keys than its key types hold apart. The relation reads a mapping's most keys as the emptiness reading does: its fields, and as many keys as each clause's key type holds apart, so dict[bool, int] and dict[Literal["a", "b"], int] are subset of Annotated[dict, MaxLen(2)], and the meet of dict[bool, int] with that bound's complement is empty, where each was undecided.

  • A meet that may hold no kind is below every set. A meet holds no kind a member cannot hold, and a complement none its inner set holds whole, so the integers met with the complement of ~str | Annotated[str, MaxLen(1)], which holds strs alone, are subset of nothing, and empty to is_empty(), where they were undecided. A meet of patterns over str beside ~str is placed at once, before any pattern's tables are built.

  • A Boolean term of length bounds over one base is read as the lengths it holds. A union, a meet or a complement of MinLen, MaxLen and Len over one str, bytes, or list or tuple of one element type holds the values of the base whose length lies in a union of intervals, so two such terms are related as their intervals are, at any length: Annotated[str, MaxLen(1000)] is subset of Annotated[str, MaxLen(64)] | Annotated[str, MinLen(65)], where it was undecided past the 584 code points the word automaton counts to, and Annotated[str, MinLen(4000)] is not_subset of Annotated[str, MinLen(5000)]. Such questions answer in microseconds where the automaton took milliseconds.

  • A sized base written bare is read as its refinement under no bound. A word, a byte string, a list, a set and a mapping each have a length at least zero, so str and Annotated[str, MinLen(0)] are one set, and the relation reads them alike: str is not_subset of Annotated[str, MaxLen(1000)] and dict[str, int] of Annotated[dict, MaxLen(2)], where only the refinement was refuted. A set's lengths run to the values its element holds apart, so Annotated[set[int], MinLen(1)] is not_subset of Annotated[set[int], MinLen(2)], on {0}. And a subject holding the empty container of its kind, a refinement under bounds that admit zero among them, is refuted below a supertype refusing it: Annotated[set[int], MinLen(0)] below Annotated[set, MinLen(1)] on set(), and Annotated[dict, MaxLen(0)] below {"a": int} on {}.

  • A word's length bound is counted by a table built directly. A length bound over str is a table of seven states a code point, which the pattern compiler reached through one of some sixteen and refused past 255 code points after building it: Annotated[str, MaxLen(2000)] met with a record's field took 35 ms to be found too large, and the first is_empty of a record of length-bounded strings over the JSON value paid it again for each new validator. Built directly, a bound is read up to 584 code points and refused at once past them, and that is_empty answers in a tenth of a millisecond. The table is built once a thread, so a relation asked again reads it back.

  • A meet holding one complement is read as the relation it is. R & ~I is empty exactly where R <= I, so where every decider declines a meet's emptiness, is_empty and the relation below nothing ask that relation's rules under the steps the query has left, as the relation is asked: a union of length bounds proved below another meets its complement in nothing to both. A meet of two records over the JSON value whose field holds a complex, met with the complement of the record of JSON fields, is subset below nothing, as the relation between the two is, and Annotated[str, Ge("\ue000")] met with the complement of Annotated[str, Ge("\ud800")] is empty. The complement of a callback, or of a class whose isinstance is code, is no set, and its meet is not read so.

  • A class with one instance is its literal, and a True step is the step 1. type(...) and type(NotImplemented) admit no subclass and make no second object, so instance_of(types.EllipsisType) is Literal[...] and instance_of(types.NotImplementedType) is Literal[NotImplemented], as NoneType is None; each pair was undecided. % reads True as the integer it is, so int is below Annotated[int, MultipleOf(True)], which was undecided. A whole float or Decimal step stays apart from the integer step: (2**53 + 1) % 2.0 is 0.0.

  • A table of constants is read for its kinds at any width. The reading that finds a kind a schema holds no value of stops after 64 nodes, and a table of constants spent one a constant, so complement(union(int, Literal[tuple(range(63))])) was undecided below nothing though every str is in it. A constant is a leaf whose kind is one question, and it spends no node now, so the complement is not_subset at every width.

  • A Fraction or a Decimal bound over the integers is read as a float one is. Python compares an int with either exactly, so the set representation reads Annotated[int, Gt(Fraction(1, 2))] as the integers from 1, the set Annotated[int, Ge(1)] is, and Annotated[int, Le(Decimal("2.5"))] as Annotated[int, Le(2)], where such an operand was left unread and the pair undecided. A subclass, an infinite or NaN Decimal, and a value past the integers the set representation holds are not read.

  • A container holds no more items than its shape can name. A length bound over a sequence was read against the sequence's own lengths, and over a set or a mapping only where the element's values were counted. Annotated[dict[str, nothing], MinLen(1)], Annotated[set[int & str], MinLen(1)], Annotated[dict[bool, int], MinLen(3)] and the closed {"a?": int} under MinLen(2) were undecided below nothing. A set of an element with no value is the empty set alone, and a mapping holds no more keys than its fields and what each clause with a value can take, its key's values kept apart, so each is empty.

  • Records told apart by a required key share no value. Two records requiring one key whose schemas share no value are disjoint, and two unions of them are read a record pair at a time, so two discriminated unions whose tags are apart meet in nothing at any width. Sixteen records a side were undecided below nothing, the meet distributed into record meets past the work a decision may spend, and thirty-two below the other's complement; two hundred now decide in a few milliseconds. Where each record pins the key to one constant, the two unions are read at the tag, only records whose constants share a value read whole, so sixteen hundred a side answer in about a millisecond, the meet and the complement alike.

  • A length every branch of a union leaves out refutes at any size. A refinement holding a value of every length its bounds admit was refuted by a length one bound leaves out, and against a union of bounds only as far as the set representation counts, about 1,400 elements of a list: Annotated[list[int], MinLen(1)] below Annotated[list[int], MaxLen(1)] | Annotated[list[int], MaxLen(3000)] was undecided. A union refuses a value each branch refuses, so the least length no branch's bounds admit, a branch of another kind admitting none, is the witness at any size, a gap between two branches among them. Bounds covering every length refute nothing.

  • A meet holds the exact empty container its members each hold. The reading found the container's kind on a bare container member alone, and read each member two ways, so Annotated[set[str], MaxLen(0)] & Annotated[set, MaxLen(1)] and Annotated[dict[str, int], MaxLen(0)] & ~{"a": int} were undecided below nothing, though set() and {} are in them. Each member is now read three ways for the exact empty container of a kind a member names: a refinement keeps it under length bounds that admit zero, and a complement holds it where its inner shape refuses it. Both meets are not_subset of nothing. A member the reading cannot read, a predicate among them, leaves the meet undecided.

  • A literal holds its constant where its own walk admits it. The relations read a literal's constant as a value only under an equality they trust, so Literal[Decimal("1.5")], a Fraction, a date, a UUID or a class with an __eq__ of its own was neither empty nor inhabited, and undecided below nothing. The walk of the literal admitting its constant now proves the literal holds it: each of those is not_subset of nothing, and a literal of a str subclass equal to "a" of Literal["A"]. A constant the walk refuses or raises on proves nothing, as before.

  • A length the supertype's bounds leave out refutes at any size. A refinement whose constraints are length bounds alone, over a base holding a value of every length -- str, bytes, a sequence with a repeated element whose positions hold a value, a mapping with one clause keyed by every str, bytes or int -- holds a value of each length its bounds admit, and one a bound of the supertype leaves out is a value outside it. Annotated[str, MaxLen(256)] is not_subset of Annotated[str, MaxLen(64)] and Annotated[str, MinLen(64)] of Annotated[str, MinLen(1000)], where the pattern a word's length is read as passed the state bound and declined; Annotated[dict[str, int], MinLen(1)] is not_subset of Annotated[dict[str, int], MinLen(2)] and holds a value at all, which a bound over a mapping's clauses did not say.

  • A union holding a complement is asked as its difference. a <= b | ~c is (a & c) & ~b empty, which is a & c <= b, both ways, and a pair every decider declines is asked so where c denotes a set, then as that difference read empty the way is_empty reads it. anything below ~dict | x is the dicts below x: dict | ~dict | x, which construction folds to anything, is refuted below ~dict | x where dict is below x alone, as it was before {"a?": object}.open() came to spell dict[anything, anything]. The dict kind's top, a member of such a union, is ~~dict, so a <= b | dict is a & ~dict <= b: X | dict is proved to hold everything where X holds every value that is not a dict. A union of a predicate and its complement is not the top and is not read so.

  • A set's and a record's lengths are read off their shapes. A set holds each member once, so it is no longer than the values its element holds apart, and a closed record's length runs from its required fields to all of them. set[Literal[1, 2]] is not_subset of Annotated[set[int], Len(0, 1)], {"a": int} is subset of Annotated[dict[str, int], Len(1, 1)], {} and Annotated[dict[str, int], Len(0, 0)] are each subset of the other, and set[Literal["a"]] & Annotated[set[int], Len(0, 1)] is not_subset of nothing, the empty set being in both, where each was undecided. Literals are counted apart within one kind, since 1 == True across two.

  • A schema meeting a complement's inner set is refuted below the complement. A <= ~B asked the meet A & B for emptiness and read only its empty answer; an inhabited meet is a value of A inside B, outside ~B, and now refutes the pair before A <= B is asked: the rules alone refute anything <= ~list[json], which the respelled pair answered after every reading had declined.

  • An order bound over str or bytes is decided as the words it admits. Python orders two words symbol by symbol, a prefix first, and the words on one side of a word are a regular set the set representation holds, so Annotated[str, Ge("a")] is not_subset of Annotated[str, Ge("b")], Annotated[str, Gt("a")] is equivalent to Annotated[str, Ge("a\x00")], Annotated[str, Lt("")] is subset of nothing, and str is below Ge("a") | Lt("a"), where each was undecided.

  • A record is refuted a shared field at a time past the node bound. Where both deciders decline a record against a record, each field the two declare is asked of the set representation alone, and one outside its counterpart refutes the pair on a subject that holds a value. A record of thirteen guarded integer fields, ~int | Ge(0) each and ~int | Ge(-1) first, is not_subset of the same record with Ge(0) first, where past twelve fields it was undecided.

  • A record the key partition cannot hold is left out of a meet of records. A meet is below the members it keeps, so a meet holding a record whose clause names part of a kind -- an opened record keyed by an integer -- beside a complement is empty where the set representation reads the rest empty. intersection(dict[str, nothing], complement({}), Validator({1: str}).open()) is subset of nothing, where it was undecided.

  • A meet subject is asked narrowed by the complements beside its unions. K & (~K | R) is K & R, and a meet on the left is now asked in that form: the guard a JSON Schema translation writes for an object keyword over a recursive JSON value, intersection(OBJ, union(complement(OBJ), R0)), is subset of R0, and two such guards are below the record holding both keys, where each was undecided. The narrowed meet is asked with steps of its own, and one asked inside another's question with that question's steps and trail, so a fixpoint met with the complement of its own lists is subset of the fixpoint without them; and a query whose steps are spent reads its two lattice bounds again, so a subject is_empty proves is below every supertype and one meeting a set in nothing below its complement.

  • A meet supertype is decided a member at a time. Where both deciders decline a pair whole, a meet on the right is asked one member at a time, and a member either refutes refutes the meet: int is not_subset of intersection(Annotated[int, Ge(0)], Annotated[object, Predicate(f)]), where the predicate refused the whole meet a lowering and the answer was undecided.

  • A set reading's difference refutes at a kind no cut reaches. A recursive reference read by the set representation is unfolded once and cut beneath the container that holds it, which changes that container's values alone, so a value the difference holds at another kind refutes. str is not_subset of recursive(lambda t: union(Annotated[str, Regex("a")], [t])), and so is int of the same fixpoint over Ge(0), MultipleOf(2) or a dict, record or tuple of t, where each was undecided.

  • A sentinel compares by identity. Python 3.15's sentinel defines an __eq__ that answers as identity does, so two sentinels are two values: the meet of their literals is subset of nothing, and one's literal is not_subset of it, where both were undecided.

  • None's kind is the literal of its one value. NoneType admits no subclass, so None is its one value, and the kind is below a set exactly where the walk admits None: None is not_subset of Literal[Color.RED], and intersection(None, complement(Literal[Color.RED])) is not_subset of nothing, where both were undecided beside a constant the set representation cannot hold.

  • A finite set of constants misses a value of every kind with infinitely many. A literal holds values of its constant's exact type alone, so a fresh object() is in no literal of a set and its complement holds a value, and a kind other than None and bool holds one no constant equals. So complement(Literal[Color.RED]) is not_subset of nothing, and int is not_subset of Literal[Color.RED], where both were undecided for a constant the set representation cannot hold: an enumeration member, an object(), a Fraction.

  • The complement of a meet holds a complemented member's values. Pushed in, the complement of a meet is the union of its members' complements, so complement(intersection(complement({"a": None}), complement({}))) holds {} and is not_subset of nothing, where it was undecided after a second spent on the records, which have no region to read it by.

  • A pattern too large to build is read by its texts. A counted Unicode class under a repetition, Regex(r"(?:\w{3,4})+"), is past the size the set representation builds an automaton to, so every relation against it was undecided. A string subject's texts are put to the validator's own matcher, as a literal's value is: every text of a pattern that has at most 64, so Regex("a") is not_subset of it and Regex("abc|abcd") is subset, and otherwise a guess at one text, which names a value where the matcher admits it, so the pattern is not_subset of nothing. A guess the matcher refuses names nothing: Regex(r"a\bb") stays undecided.

  • A meet of sequences each holding the empty one holds it. The empty list is a value of every list shape with no prefix and of every length bound that admits zero, so intersection([], RI) with RI = recursive(lambda t: union(int, [t])) is not_subset of nothing, and so is recursive(lambda t: intersection([], [t])), where both were undecided while the element was a definition being resolved.

  • The set representation reads scalars nested past its depth. Its depth bound exists for the containers a build starts -- an automaton, a powerset, a record lattice -- and every node above one still counts, so a container is refused where it was; a scalar node past the depth starts no build and is read. intersection(int, complement(intersection(int, complement(E)))) with E the even integers is not_subset of nothing, and the same over the literals {1, 2, 3} or a bound, where each was undecided once the meets and complements nested the constants six deep.

  • A sequence's length is read at both ends of a relation. A list bounded to length zero is the empty list, so Annotated[list[None], Len(0, 0)] is subset of a list of any element, and a list shape whose element has a value is refuted below a maximum length by one copy more than it admits, so a list of integers is not_subset of the same list under Len(0, 1) -- what a translation from JSON Schema writes for maxItems -- where both were undecided whenever the element was one the set representation cannot hold.

  • A refinement of a union is the union of its refined branches. A constraint is asked of one value at a time, so Annotated[int | float, Ge(0)] is the non-negative ints and the non-negative floats, and is decided as each is: intersection(None, Annotated[int | float, Le(1)]) is empty, bool is subset of Annotated[int | float, Ge(-2)], and the base written as a union is subset of the union of the refinements both ways, where each of these was undecided. A constraint is Python's own operation, whose error the walk reads as a failed check, so None under any constraint but a predicate is empty: Annotated[int | None, Ge(0)] is Annotated[int, Ge(0)].

  • A float bound over the integers is read at its floor or its ceiling. Python compares an int with a float exactly, so the set representation reads Annotated[int, Gt(0.5)] as the integers from 1, the set Annotated[int, Ge(1)] is, where a float operand over the integers was left unread and the pair undecided. Gt(math.inf) holds no integer and Lt(math.inf) every one.

  • A meet is refuted below a meet it shares no value with. a <= b with a & b empty holds only of an empty a, so where every decider declines a meet against a meet, a subject that holds a value is not_subset where the two meet in nothing. Two objects a translation from JSON Schema guards to their kind, each a recursive record with a tag of its own, are not_subset of each other, where all 28 pairs of eight such schemas were undecided.

  • A union in a meet is narrowed by the complements beside it. k & (~k | x) is k & x, so a branch that is the complement of a member beside its union is dropped before anything is distributed, and any number of keywords a translation from JSON Schema guards to one kind is read as the meet of what they guard: an object schema with three guarded keywords, two of them tags fixed two ways, is empty, where a meet of more than two such guards was undecided. A narrowed meet the readings leave undecided hands the meet as written to the readings after it, which distribute it through a reference.

  • Two branches splitting a set by another are read as the set they split. (r & ~b) | (r & b) is r wherever b answers alike however often it is asked, so a union holding two such branches is decided as that set: the recursive JSON value is subset of its own split by bool, and a list of JSON values of its split by list[int], where both were undecided, and a value outside r is not_subset. A split by a predicate is not merged.

  • A type defined in C lays down the layout its instance size says. Python refuses a class deriving from two types unless the layout one lays down extends the other's, and a static type lays down one of its own where its instance is larger than its base's. complex meets no JSON kind, so intersection(complex, int) is empty and Validator(complex) is subset of the complement of a JSON value, where both were undecided, and an exception meets no kind either. ValueError and TypeError carry the layout BaseException lays down, and their meet is not called empty. PyPy names no size, so there these pairs are undecided.

  • A pair every decider declines is asked in its other spellings. a <= b is a & ~b holding nothing, so where the rules, the set representation and the parts all decline, a difference holding every value of some kind refutes the pair whatever shape the subject has, and against a complement ~c the pair is asked as the meet with c below nothing, as c below the complement of the subject, and as that meet read empty the way is_empty reads it, a union a member at a time, so anything is below the complement of a union of members empty to different readings. anything is not_subset of the complement of a list of JSON values, where it was undecided, and on drawn translation shapes the plain spelling of an inclusion, an emptiness, a disjointness or a union subject declines where another spelling decides about a tenth as often.

  • A word boundary at an end of a pattern is read as the character it asks about. A pattern matches the whole text, so a \b or \B leading or closing it asks only whether the first or the last character is a word character, and the set representation reads it so: Regex(r"\bab\b") is the set Regex("ab") is, where both directions were undecided. A relation turning on a boundary between two parts of a pattern declines.

  • An integer step is refuted by a multiple the other step does not divide. A refinement of int by one integer step and integer bounds holds exactly the multiples of its step between its bounds, so its emptiness is read exactly, and it is not_subset of a refinement carrying an integer step where one of those multiples is no multiple of that step: MultipleOf(5000) against MultipleOf(3) at 5000, and MultipleOf(6) against MultipleOf(2500) at 6, where both were undecided.

  • A union is decided a part at a time where the pair declines whole. A union subject is asked a member at a time and a union supertype is narrowed to the branches the subject shares a value with, by both deciders, where the set representation refuses the whole pair past its node bound or could only prove it for a reference it holds: a union of seven to two hundred tagged records against the same records shifted is not_subset, a union of 32 or more patterns is subset of a pattern each is below, and str is not_subset of a fixpoint of lists beside a pattern, where all three were undecided. The parts are asked while the query has a step left: a part is a reading no step counts, and a pair the rules spend every step on, five hundred tagged records against five hundred, has as many parts as members and branches. A union is refuted by a member whose refutation stands, whatever its other members' emptiness reads, so a union of a recursive schema and a pattern is not_subset of nothing. is_empty reads a union a member at a time too, so a union the relation proves below nothing is read empty.

  • A subject holding every value of a kind the supertype holds none of is not_subset. Every kind is inhabited, so anything and a complement of a schema missing a kind are refuted at a value of that kind against a supertype -- a union, a meet, or a recursive schema read through its definition -- that holds none: anything and complement(J) are not_subset of the JSON universe J at b"", and anything of complement(J) at None, where all three were undecided. A meet is also read by a member that is a union of kinded branches, so a list met with None | ((int | float) & ~bool & bounds) is empty.

  • A complemented union or meet is read with its complement pushed in. complement(union(a, b)) is the meet of the complements and complement(intersection(a, b)) the union of them, and a relation with such a subject is decided where that reading is the supertype or has it among its members. complement(union(str, complement(list[list[int]]))) is subset of list[list[int]], and the complement of a union is subset of the meet of the complements however its members nest, where both were undecided.

  • A musllinux wheel for CPython 3.15, its free-threaded build and PyPy 3.12. The musl build image carries all three, and the release builds a wheel for every interpreter it carries, so an Alpine install of 3.15 takes a wheel where it compiled the source distribution. The release runs the product suite on the 3.15 wheel in python:3.15-alpine. No Alpine image carries a free-threaded CPython or a PyPy, so the other two are built and not loaded.

Changed

  • The floor is Python 3.11. CPython 3.10 reached the end of its security support in October 2026, and the first release after that drops it, as docs/dev/releasing.md states: no wheel is built for it, and requires-python is >=3.11. Every release from 3.11 to 3.15 is supported, the free-threaded builds of 3.14 and 3.15 among them, and 3.16 runs as a forgiven prerelease lane. The readings typing_extensions gave a form only 3.10 spelled with an object of its own are gone with it, and the refusal of a + after a quantifier says re reads it as possessive without naming the release that began to, since every supported re does.

  • A class key opens and closes as a kind does. dict[K, Any].open() is dict[anything, anything], and closing that gives {}, as dict[int, Any].open().close() does, where it came back as dict[K, Any]. dict[complement(K), Any], which opens to the same term, came back as the other half and admitted a key close refuses, and it gives {} too, so the round trip is at most closing with no exception. {K: Any, str: int} keeps its exact round trip.

Fixed

  • open and close give one term however often they are applied. {anything: int, int: anything, complement(int): anything} closes to itself, its first clause claiming every key, where it closed to dict[anything, anything] and a second close took that to {}. {int: int, str: int, union(int, str): complement(int)} opens to dict[anything, anything] in one application, where it took two. No first application admits another set.

  • Every key reads alike over a class, whose complement law does not fold. {complement(K): int, anything: anything} opens to one term however often it is opened, where a second open wrote a longer key over the same set, and closing it after opening gives what closing it gives, where the round trip kept the keys open freed.

  • A standard-library value type is the class the interpreter's module binds. The relations read Decimal, Fraction, the datetime types, UUID, the ipaddress types and the pathlib paths as ordering, dividing and measuring as their == says, and found each by identity with the class its module binds in sys.modules. A program's own fractions.py or decimal.py, beside its script, is imported under that name, so a class of the program's was read as the standard library's, its order and its equality trusted as a value type's. A module is now the standard library's where the import system loaded it from the directory sysconfig.get_path("stdlib") names, or froze or built it in, and a module of the program's own leaves its classes declined: beside a Fraction of the program's comparing as 5, Annotated[int, Ge(1)] against Annotated[int, Gt(Fraction(1))] is undecided, 2 being in the one and not the other.

  • A refutation stands on a length every interpreter builds. A container holds its items in one allocation, which the allocator refuses past sys.maxsize bytes, so CPython builds no list longer than sys.maxsize // 8 and no set past about a fifty-third of it. The relations read a length up to sys.maxsize as one a value has: Annotated[list[int], MinLen(sys.maxsize // 8 + 1)] was not_subset of nothing, on a list no interpreter builds. A witness is now given a length at most sys.maxsize // 128, which every kind reaches on every supported interpreter, and a pair whose witness is longer is undecided.

  • A field wrapped past the qualifiers read is refused as too deep. A dict literal refuses Required and NotRequired on a field, read through Annotated and ReadOnly up to eight layers. Past them the field was built with the qualifier dropped: {"a": ReadOnly[...[NotRequired[int]]]} eight layers down required the key the qualifier calls optional, and "a?" over Required[int] the other way. The field is refused there as nesting too deep, as a wrapper naming itself already was.

  • A Decimal bound with a vast exponent is not rounded to an int. The rule that finds no integer between two bounds rounded each to an int, and a Decimal takes time quadratic in its digits to become one: Annotated[int, Gt(Decimal("1e999999"))].is_empty() took 26 seconds, and a larger exponent did not end. Past 4,300 digits, CPython's own default for converting an int to text, the bound is not rounded and the rule declines. The answer above is read in a fraction of a millisecond.

  • A quantifier re refuses for repeating no atom is refused. re repeats an atom and refuses a quantifier on a quantifier, a{2}{3} or a**, as a "multiple repeat", and one on an assertion, ^* or \b+, as "nothing to repeat". Each was built here with a meaning of this engine's, a{2}{3} admitting "aaaaaa", which no re call could check. Each now raises a ValueError in re's words. A lazy quantifier, a*?, is read as before, and (?:a{2}){3} repeats a repetition in both.

  • No value is longer than sys.maxsize. CPython counts a length in a Py_ssize_t and len() raises past sys.maxsize, while a length bound was read up to 2**64. Annotated[str, MinLen(2**63)], which admits no value, was refuted below nothing, and list[int], tuple[int, ...], set[int] and frozenset[int] were refuted below MaxLen(sys.maxsize) on a value one longer, which no container is. A length bound past sys.maxsize is now refused at build as one no value has, and a bound at it refutes nothing for being exceeded.

  • A signaling Decimal NaN is refused as a bound or a step, as nan is. Annotated[int, Ge(Decimal("sNaN"))] and MultipleOf(Decimal("sNaN")) were built and admitted no value. The conversion to a float that reads nan and the quiet Decimal("NaN") raises for a signaling one, and every comparison or remainder with it raises InvalidOperation, which the walk reads as a refusal. Both are refused at construction with the ValueError nan gets, read by Decimal.is_nan, a subclass overriding that method included.

  • A class prints as its name only where its name builds the meet. A class met with a shape or a record it does not declare printed as the class, which reads back as every instance of it: intersection(list[int], Plain) as Plain, intersection(Plain, P) for a protocol P as Plain, and intersection(instance_of(Pair), tuple[bool]), for a named tuple declaring an int, as Pair. A generic dataclass applied printed as its name, Box[int] as Box, which reads back as its parameters' defaults or is refused. A class now prints as its name where the name builds the class met with that member, and the meet prints whole elsewhere: intersection(list[int], Plain), intersection(Plain, object(x=int)), intersection(tuple[bool], instance_of(Pair)) and intersection(instance_of(Box), object(item=int)). A union's branch label names such a meet by its members, list and Plain.

  • An enumeration is its members to a refutation as to a proof. Pair, an Enum whose members carry no x, was proved below Literal[Pair.A, Pair.B] and that union below ~X for a protocol X declaring x, and refuted below ~X itself, on an instance object.__new__ makes past the members; Pair & X was refuted below nothing and proved below ~X | int. An enumeration read as the union of its members is that union on both sides: Pair is below ~X, and no relation of the class stands on an instance its members are not. A member is read as it stands, so one given an x refutes the class below ~X as it refutes its own literal.

  • A frozen dict literal's refusal names the schemas that admit one. On 3.15, frozendict(a=int) was refused with a pointer to the dict literal {"a": int} and to dict[K, V], both of which refuse every frozen dict, since no node reads a frozen dict's keys. The refusal names collections.abc.Mapping and instance_of(frozendict), which admit one whole.

  • A type variable is its own class's parameter. class IntBoxOf(Box[int], Generic[T]) reuses the T its base declares a field with, and typing reads the two as two parameters: Box[int] closes Box's, and IntBoxOf's is another, the same object in another scope. Every field was substituted through one table keyed by the variable, so IntBoxOf[str] was refused as binding T to int and str at once, and so was a base applied to its class's parameters crossed. Each class keeps a scope of its own, a base's arguments read through the class deriving from it, and a field is substituted in the scope of the class that declares it: IntBoxOf[str] holds an int at the base's field and a str at its own. A class two bases reach under two arguments is still refused. A PEP 696 default naming an earlier parameter takes that parameter's binding in the same application: with U defaulting to list[T], Pairs[int] reads U as list[int], applied directly or as a base applied short.

  • A member deep by a clause's key alone is left out of the last thinned reading. A meet the set representation cannot read whole is read without the members it cannot hold, a superset whose emptiness proves the meet's. A map's key is read for the labels it covers, never descended, so a member at the edge of the depth by its key alone was kept, and beside literal-keyed records the meet with it was not proved empty where the meet without it is: 0.0.22 declined a share of the emptiness proofs 0.0.21 made over maps -- {} alone, outside dict[Literal[True], None]'s complement. A last reading counts a key as a level and leaves such a member out, after the two that keep it.

  • A length bound no automaton could count to is refused before it is built. A str or bytes length bound is read as a pattern counting code points or bytes, and the pattern's compiler unrolls the count into that many copies before any limit is read: Annotated[str, MinLen(999_999)] against MinLen(1_000_000) held three gigabytes, and a bound past the address space aborted the interpreter with no Python exception, on every release. A table counting to a bound holds a state for each count, so a bound past the 4,094 a table of 4,096 states counts to is refused before its pattern is written, as a sequence's bound already was, and the compiler is held to the size the table build is held to, for every pattern. Both relations answer at once.

  • A constant the walk stopped on proves and refutes nothing. A literal is decided by walking its constant through the supertype, and a predicate that raises on the constant stops that walk, which refuses the value from the set and from its complement alike. The relation read the refusal as a value outside the set: Literal[5] was not_subset of T | ~T for T an int refined by a predicate raising on every value, a union holding every value, and through the respelling of ~(T | ~T) <= ~Literal[5] as its contrapositive, the empty ~(T | ~T) was refuted below it too. The constant is read as a complement reads its inner walk: refused only where the walk decided it, admitted only where a branch admitted it, and neither otherwise. The same for an enumeration's members, None, and the texts a pattern too large to build is read by.

  • A bound whose operand orders on its own renders marked. A bound of a subclass of int, float, str or bytes printed as the builtin's bound, but where the subclass writes a comparison or a remainder of its own the walk reads that one first, so the two are two sets: Ge(RevInt(5)), with RevInt ordered the other way round, holds 0, and its meet with complement(Annotated[int, Ge(5)]) printed as one that reads back empty. The operand prints as a literal of it does, Ge(<RevInt: 5>), a syntax error where it is read; a subclass keeping the builtin's methods prints as before.

  • Opening or closing a schema twice gives the schema once did. Validator({"a": int, "b?": anything}).open() kept b, which the closed record says something of, beside the catch-all the opening wrote, which says the same of b; a second open dropped it, so o.open() != o by == and their hashes differed. The first rewrite drops a name the clauses it writes already say, and either operator applied twice is the term it gave once. A supertype that folds to dict this way is still decided against a complement of a union: where every decider declines, ~(~x | y) is asked as x & ~y, so it is subset of dict where x is a set of dicts.

  • annotated_types.doc() is ignored under annotated-types 0.8.0. Where typing_extensions has no Doc to lend, the release makes a class of its own named Doc, which earlier releases named DocInfo, and Annotated[int, doc("a count")] was refused as a constraint valgebra does not check. It documents an annotation and excludes no value, and is ignored as DocInfo is.

  • A string a type alias substitutes is refused as a forward reference. type Keyed[T] = dict[str, T] applied to "" raised SyntaxError from typing, which reads a string it substitutes as the text of an annotation and finds no expression in that one, where Keyed["int"] was refused as the forward reference it is. Both raise NotImplementedError; a string for a parameter the alias's value does not name is never read.

  • A meet two of whose members share no value is below anything at once. A meet subject asked each member against the supertype before reading its own emptiness, so intersection(complement(bool), float, dict[str, X]) against a large recursive schema walked that schema for seconds before the meet's empty float & dict pair answered it. The pair is read first.

  • A table of constants below a complemented table is one question. Literal[0, ..., 3999] against complement(Literal[-1, ..., -4000]) is the two tables sharing no value, which the bindings answer for both tables at once: it is decided in 3 ms, where each constant was asked against the whole other table and the relation took 1.2 s, quadratic in the width. The meet's emptiness, intersection(A, B) below nothing, read the tables whole already.

  • A counted Unicode class written as an ordinary bound builds. The walk's pattern compiles under a size limit of 32 MiB, three times the regex crate's default, which refused Annotated[str, Regex(r"\w{1,255}")] and every count past \w{0,209} while re takes them. \w{1,1000} is refused as before, naming the limit. A validator keeps every pattern's program, so its patterns compile within 256 MiB together, eight programs at that bound, each text once, when it is built: a record of sixteen ^[\w.-]{1,n}$ fields keeps 43 MB and builds, and eighteen \w{1,255} fit while a nineteenth is refused there, where a hundred held a gigabyte and aborted the interpreter at the first value.

  • One depth bound raises one type. An annotation nested past MAX_SCHEMA_DEPTH raises the ValueError a schema built past it raises, at the bound and past it, where 129 levels and more raised NotImplementedError. A class whose own type appears in its fields is refused with NotImplementedError where it is reached again while its fields are being built, under the type arguments it is applied to, rather than after descending to the bound: Chain[int] naming Chain[int] is refused, and Box[Box[int]] builds.

  • A length bound equal to a whole number is that length, and a truth value bounding a number is the integer it is. len is an int, so Annotated[str, MaxLen(2.0)] admits what MaxLen(2) does, and is built as it, where it was refused; and typing caches Annotated by equality, so a correct MaxLen(2) was refused in a process that wrote MaxLen(2.0) first. An integral Fraction or Decimal length reads the same way, and one equal to no whole length is refused, as is a number of any other type, whose int() and == are its own. Le(True) is Le(1) to the decision, so Annotated[float, Le(True)] is not_subset of nothing, where it was undecided.

  • A recursive definition being resolved is read as empty at positive positions only. The emptiness decision reads a definition it is resolving as empty, the least fixpoint, and a relation it asks on the way could drop a branch, a component or a slot of the relation's supertype by that reading, which narrows the supertype and can refute a relation that holds. While a definition is being resolved, such a part is told apart from the subject by the kinds each may hold, a reference read through its definition. No released answer is known to have been refuted this way.

  • A reading that cannot decide a meet hands it to the next. A meet's readings are each sound alone, so one that ends undecided passes the meet on rather than answering for it. intersection(union(complement(DN), DB), Validator({"a": int}), complement(dict)), with DN and DB mappings keyed by Literal["a"], is subset of nothing, as on 0.0.21, where 0.0.22 distributed the union, ended undecided and asked nothing after it: of the answers 0.0.21 gives on 60,000 drawn record schemas, 0.0.22 left 136 undecided three combinators deep and 153 four deep.

  • The emptiness decision reads a reference in the complement law as construction does. A recursive schema is a set where its definition is one, and the decision reads it through its definitions, so a meet of a recursive schema holding a class with its own complement is empty: x & ~x with x = intersection(json, list[complex]) is is_empty(), where it was False.

  • is_empty reads a complemented union as a relation below nothing does. A complemented union is empty where its complements, pushed one level in, meet in nothing as they are built, which is how the relation reads it below nothing, so complement(union(complement(str), complement(intersection(json, complement(str))))).is_empty() is True, where it was False beside relation_to(nothing) == "subset".

  • A relation the two schemas settle as written is never undecided for want of a step. A schema against a union that holds it, a meet against one of its own members, and a schema against itself are answered before any rule spends the decision budget. Records a translation from JSON Schema guards to objects and nests four deep are subset of a union holding them, and a recursive record met with a nested closed one is subset of that recursive record, where 0.0.21 and 0.0.22 spent the budget on the meet's members and answered undecided.

  • A Len whose minimum is below zero is refused. annotated_types unpacks Len(-1) to no lower bound, so Annotated[str, Len(-1)] built the bare str while MinLen(-1) was refused for naming no length a value can have. Both raise that ValueError.

  • A required key whose name ends in ? renders marked. No dict display requires such a key, since the display reads a trailing ? as optional, and repr printed TypedDict("TD", {"a?": int}) as {'a?': int, str: anything}, the display of a record whose a is optional. It prints {<required: 'a?'>: int, str: anything}, a syntax error where it is read, as a constant whose repr would read back as another value does.

Security

  • A constant proves its literal only where the values equal to it read alike. Literal[CI("a")], with CI a str subclass whose == ignores case, holds CI("A"), which Regex("a") refuses; the literal was subset of that pattern, and its meet with the pattern's complement is_empty(). The same held of int, float and bytes subclasses with an == of their own against bounds, lengths and steps, and of a literal against another literal of a class whose == is not transitive. The answers were wrong in 0.0.1 through 0.0.22. A proof by the constant stands where the values == joins to it read alike to the supertype's atoms: an exact builtin, a builtin subclass keeping the builtin's == (an IntEnum), a standard-library value type (Decimal), or identity. A class is a standard-library type by identity with the class its module binds, never by the __module__ it states.

  • Two bounds over lists or tuples are not compared. Annotated[list[object], Ge([2])] holds [2 + 0j], whose one item equals 2, and Annotated[list[object], Ge([1])] does not, since ordering 2 + 0j against 1 raises; the first was subset of the second. The answer was wrong in 0.0.1 through 0.0.22. A sequence orders item by item, so no order between two list or tuple bounds is an order of the values; two set bounds compare by inclusion and stay decided.

  • Two bounds are compared only where each operand orders as the walk reads it. Annotated[int, Ge(Mod7(1))], with Mod7 an int subclass equal to every integer congruent to it modulo 7, admits 1, since 1 >= Mod7(1) reads the stored 1; it was equivalent to Annotated[int, Ge(8)], because Mod7(1) == 8. That answer was wrong in 0.0.1 through 0.0.22. A str or int subclass ordering by its own methods was read the same way, so a tighter bound was proved below a looser one that a value refutes, and an empty interval was reported inhabited. A bound whose operand is a builtin subclass with an ==, an order or a rounding of its own is compared with no other bound, and so is one whose operand is of a class of no builtin, unless that class is exactly one of the standard library's value types (Decimal, Fraction, the dates): Python implies no relationship among a class's comparison operators.

  • A class is read where Python dispatches its hooks, not through its metaclass. Whether a class overrides isinstance, issubclass or ==, whether a builtin subclass's __len__ and __iter__ are the base's own, which slots and descriptors its namespace holds and in what order its bases stand were read through getattr on the class, which asks the metaclass first. Python dispatches each through what the type's own namespaces hold along the order it laid down, and asks no __getattribute__, so a metaclass answering with the plain one hid the class's own: a class whose __subclasscheck__ answers True was decided above a class isinstance says it is not above, two instances of a class with an equality of its own were two disjoint literals, a str subclass whose __len__ answers 0 met MaxLen(1) with "abc", and an order the metaclass reported decided a meet empty that held an instance. A hidden __subclasscheck__ was read wrong in 0.0.1 through 0.0.22, and a hidden __eq__ in 0.0.10 through 0.0.22. Each is read as inspect.getattr_static reads it now, at no cost to a class whose metaclass is type.

  • A class's layout is the one Python laid down. A class given __slots__ after it was made -- by a decorator, say -- lays down no slot, yet was read as laid out: its meet with any slotted class, and its relation to the complement of int, were decided empty, beside instances Python builds of both. Such a meet was answered empty in 0.0.14 through 0.0.22. A class whose metaclass's mro() leaves out the builtin it derives from was read as laid out on nothing, though every instance is laid out on that builtin, and a slot whose descriptor an assignment replaced was read as unset rather than as the value every instance reads. The layout is read off __base__ and off the member descriptors Python makes with a class.

  • An enumeration making an instance past its members is not their union. An Enum whose _missing_ returns a new instance for any value was decided equivalent to the Literal of its members, though E(5) is an instance of it and of no member's literal; an enumeration whose metaclass leaves a member out of its iteration was decided below the members it lists. The answers were wrong in 0.0.10 through 0.0.22. An enumeration is read as the union of its members only where its _missing_ is Enum's and its metaclass's __iter__ and __call__ are EnumMeta's.

  • An enumeration with a subclass is read as its class. An enumeration with members is read as the union of them because the class makes no other instance. No class statement derives from one, but on CPython 3.15 __bases__ assigned to a plain class does, and that class's own constructor makes an instance of the enumeration that is no member: Hue was decided subset of Literal[Hue.RED, Hue.GREEN] with such an instance in the first and not the second. The answer was wrong in 0.0.10 through 0.0.22. An enumeration type.__subclasses__ lists a subclass of, as it stands when asked, is read as the class it is.

  • A TypedDict qualifier given as a default or as extra_items is refused. A class left unapplied takes each parameter's default, which reaches its fields as an argument does, and NotRequired[int] as the default read as the item's own: the key turned optional, {} admitted and the class proved equal to one declaring a: NotRequired[int], though the runtime keeps a required; a Required default turned an optional key required, and a dataclass's field dropped the qualifier. The reading was wrong in 0.0.21 and 0.0.22. A qualifier as a parameter's default is refused as the same qualifier written as the argument is, bare or under Annotated. Required and NotRequired as extra_items, which PEP 728 calls an error, are refused there too, where they built as the type they wrap; ReadOnly is read through.

  • A TypedDict qualifier given as a type argument is refused. Required, NotRequired and ReadOnly qualify an item where it is declared, and the typing spec admits them nowhere else. Holds[NotRequired[int]], for a generic TypedDict declaring a: X, read the qualifier as the item's own: a turned optional and the class equaled one declaring a: NotRequired[int], where the runtime keeps a required; a dataclass applied to one dropped it. The reading was wrong in 0.0.21 and 0.0.22. A class applied to a qualifier, bare or under Annotated, or a base written applied to one, is refused, naming the class the field is declared in.

  • A class over a list of types or a signature is refused applied. A TypeVarTuple stands for a list of types, and Row[int, str] binds it to (int, str), so a field tuple[*Ts] is tuple[int, str]; the parameter was bound to the argument at its position, so Row[int, str] held {"a": (1,)}, refused {"a": (1, "a")}, and equaled Row[int]. The reading was wrong in 0.0.21 and 0.0.22. A generic class whose parameters are not all TypeVars is refused where it is applied, takes a default for one, or is a base written applied, as an alias declaring one already is; written bare, it is read where no field names the parameter. A ParamSpec alike.

  • A type parameter's default written as a string is refused. PEP 696 makes a default a type expression, and a string there a forward reference, which the runtime keeps as written. A field that is the parameter alone read it as the value it is: under W = TypeVar("W", default="int"), a: W was the literal 'int', admitting the word and refusing every integer, in a TypedDict, a dataclass and a NamedTuple left unapplied. The reading was wrong in 0.0.21 and 0.0.22. It is refused as a forward reference, as the same string written as the argument is and as list[W] already was.

  • A TypedDict's extra_items given as a string is the type it names. PEP 728 takes a type expression there, and a string where one goes is a string annotation, which the runtime keeps as written. It was read as the value it is: extra_items="int" built {'total': int, str: Literal['int']}, admitting the word as an extra value and refusing every integer, in the class statement and the functional form alike and in a subclass inheriting it. The reading was wrong in 0.0.10 through 0.0.22. It is resolved as the class's own annotations are, in the module that defines the class. A class whose extra items are its own type is refused as a class whose fields name it is, with the hint to write it with recursive(...).

  • A deep walk on PyPy stops where PyPy has stack to answer. PyPy sizes the stack its C-API calls may use by the recursion limit, and a walk that reached it before its own bounds ended the process: under sys.setrecursionlimit(60), validating a list nested fifty deep did, on every PyPy wheel, 0.0.1 through 0.0.22. The walk now asks PyPy's stack check as it goes deeper, and refuses at recursion_limit where PyPy has no room, so the value is no member and validate raises an error the caller catches. Under the default limit the answers are unchanged, and CPython is untouched.

0.0.22 - 2026-10-27

Three meets decided where the relations declined, and a relation 0.0.21 made dearer: three additions and one fix. A meet is disjoint from what one of its members is, a meet of records holds the dict of the fields they require, and a meet of a few unions is decided clause by clause, so the meets a translation from JSON Schema writes when it guards each keyword to its kind answer where they answered undecided. The fix reads the depth the set representation refuses off a schema before anything is built, where 0.0.21 built the reading and lowered the supertype for an answer that could only be undecided.

Against 0.0.21, two records spelled OBJ & (~OBJ | R) & (~OBJ | REQ) are related in 76% fewer instructions, and their recursive spelling in 52% fewer, which is 32% more than on 0.0.20. The decision pairs that reach the set representation count 0.26% more, for the depth read off each schema before it is built and the switch that reads a meet by its members' kinds; the relations that hold and the corpus asked of the sets count 0.04% and 0.06% more, and the refuting and length-bound workloads 0.27% and 0.15% fewer. Every other shape the instruction gates count reads within 0.02% of 0.0.21. The profiled wheels' walk on CPython 3.12, 3.14 and 3.15 counts what 0.0.21 built from its tag counts, to the instruction, but where an allocator moves a shape that allocates and in the layout 3.15's build gives the walk: a literal's check one instruction more, a recursive schema's twelve fewer.

Added

  • A meet is disjoint from what one of its members is. A schema a union holds as a branch, written as a meet, is read by its kinds as the meet's own members are, so int met with a union of two string patterns each guarded to strings, intersection(str, union(complement(str), Annotated[str, Regex(p)])) as a translation from JSON Schema writes a pattern, is empty where it was undecided, and an integer is not_subset of such a union.
  • A meet of records holds the dict of the fields they require. Records met in a meet, open ones among them, are one record whose fields hold what every record gives each name, through its field or the catch-all over its kind, so the meet is empty where a required field has no value and holds the dict of those fields where each has one. Two open records over a recursive universe that fix two different tags are not_subset of each other where they were undecided, and {"tag": str} met with dict[str, int] is empty.
  • A meet of a few unions is decided clause by clause. A meet whose unions span four clauses at most, no branch of them a meet or a union, is read as their union, each clause decided on its own, where only a union beside a recursive reference was. A translation from JSON Schema guards each keyword to its kind, OBJ & (~OBJ | R) & (~OBJ | Q), so two tags fixed two ways meet in nothing and one tag beside a required one holds a value, where both were undecided. A relation whose subject the set representation reads without such a meet, which the rules now find a value of, is not built for the reading that can only find it inhabited.

Fixed

  • A relation the set representation refuses for depth costs a walk, not a build. 0.0.21 read a meet nested past the depth the set representation descends without the members past it, building the members it kept, and lowered the supertype as well, where the answer could only be undecided. A relation between two records each spelled OBJ & (~OBJ | R) & (~OBJ | REQ), as a JSON Schema translation guards a keyword to its kind, counted 85% more instructions than on 0.0.20. The depth is read off the schema before anything is built, and a reading the rules find a value of is built only for a relation whose supertype the set representation reads: the same relation counts 76% fewer instructions than on 0.0.21 and 55% fewer than on 0.0.20, with the same answer. Its recursive spelling, $ref'd as a JSON Schema translation writes it, counts 52% fewer than on 0.0.21 and 32% more than on 0.0.20, the rules reading the meets the decision asks on the way. A meet holding a member past the depth is read without it whatever else the member holds, and a member whose deepest node is a mapping's key is kept, where each was left unread.

0.0.21 - 2026-10-26

Four relations decided where they declined, readings the typing spec gives that the frontend refused or misread, and a wrong subset proof withdrawn: four additions, one change, six fixes and two security fixes. A generic TypedDict, dataclass or NamedTuple applied is read with its arguments in place, and a meet holding a literal, a meet beside a member the set representation cannot read, and a meet of records answer where they answered undecided. A copy of a validator is the validator. The fixes read a type alias unpacked into a tuple and a class whose __getattr__ answers every name, and refuse three spellings that name no one set: Required and NotRequired on one item, bare Generic, and a dict display whose two keys build one key schema. The security fixes are a meet holding a union twice beside a recursive reference, answered empty though a value is in it, and a complement of a definition two of its members share, whose walk took seconds near the depth bound. The entries under Security name the releases each reached. Upgrade from any of them.

Against 0.0.20, a fifty-field TypedDict whose five optional fields are refined compiles in 11% fewer instructions, and explaining a failure and relating two validators count up to 0.5% fewer. Every other shape the instruction gates count reads within 0.1% of 0.0.20, the profiled wheel's flat, but a dataclass's compilation, 0.05% more for the test that reads whether the class is generic.

Added

  • A generic TypedDict, dataclass or NamedTuple applied is read with its arguments in place. Box[int] for a dataclass Box(Generic[T]) with a field item: T is a Box whose item holds an int, where it was refused, and so is a class deriving from one applied, class IntBox(Box[int]), or a TypedDict child of Pair[int], however deep the derivation, which built nothing either: the field read T and was refused as a type variable. A parameter neither applied nor bound takes its PEP 696 default; one with none, named by a field of the class written bare, is refused naming the class and the variable, and so is a type variable two bases bind to two types. A generic class isinstance alone answers is refused applied, as it was. A generic TypedDict and NamedTuple need 3.11.
  • A meet holding a literal is decided one constant at a time. Each constant is walked through the other members: the meet is inhabited where every member admits one, and empty where each is refused by some member. So Literal["paid"] & ~(Literal["paid"] & J), for a recursive universe J the set representation does not read deep enough, is proved empty where it was undecided, and so is a literal set minus the complements of that universe met into each piece, the schema a planner meeting every member with its universe builds. A refusal speaks for the literal only where nothing the member asks tells equal values apart, as a literal below a schema reads it, and a predicate that raises on the constant decides nothing.
  • A meet proved empty stays empty beside a member the set representation cannot read. Two patterns no string matches both of were proved apart, and beside a predicate, or beside a member nested past the depth the set representation reads -- the complement of a literal met with a recursive universe is one -- the meet was undecided. Such a member is left out of the reading, which is a superset of the meet, so its emptiness is a proof, as a meet of three members and as one Annotated holding all three constraints. The reading proves emptiness and only that: the meet without the member holding a value refutes nothing.
  • Records met in a meet are related as one record. The meet of two open records whose catch-all is a recursive universe -- {"tier": Literal["free", "pro"], str: json} and {"tier": Literal["pro", "enterprise"], str: json} -- was undecided below {"tier": Literal["pro"], str: json}, minus it, and as one record minus the third below the other's complement. The records are met field by field into one record, a field holding what every record gives its name and missing only where every record lets it be, and the record rule relates that record as it relates one, so all three are proved. A member of another shape beside the records leaves the proof standing, and so does a meet below a complement, asked as the meet holding the complement's inner, as any other subject is.

Changed

  • A copy of a validator is the validator itself. copy.copy(v) is v and copy.deepcopy(v) is v, as the standard library gives back an immutable tuple or frozenset, where each built a new validator over the same schema, which held the same set and computed its hash and its per-node tables again.

Fixed

  • An attribute a __getattr__ hook answers is never read as missing. A refutation about a class stands on a direct instance of it, and the relations read a name the instance's __dict__ lacks, a slot left unset and a name a class without a __dict__ does not define as able to be missing where the class defines __getattr__ -- which answers exactly those lookups. So a class whose hook returns 1 for every name, refusing every subclass, was answered not_subset of a protocol a: object that every instance of it satisfies, and its meet with that protocol's complement was answered inhabited, in 0.0.16 through 0.0.20. Beside such a hook a slot or a dictionary entry holds any value it is assigned and is never missing, and a name neither can hold is the hook's answer: such a pair answers undecided, and one refuted by a value an assignment puts there -- a = "x" against a protocol a: int -- stays not_subset.
  • A type alias unpacked into a tuple is the tuple it names. tuple[str, *Tail] under type Tail = tuple[int, ...] builds tuple[str, *tuple[int, ...]], as every type checker reads it, where it was refused with a reason that was false of it: an applied generic alias splices with its arguments in place, a fixed tuple's alias splices its elements, and an alias of an alias is read through. An alias of something that is not a tuple is refused naming what it stands for, and so are aliases naming each other in a cycle and an alias that unpacks itself, type Rec = tuple[int, *Rec], which has no finite length.
  • Required and NotRequired on one TypedDict item are refused. The typing spec makes the pair an error, and the two read as different records -- the runtime's key sets take the key as required and pydantic as optional -- where the outermost was read. A qualifier nested in itself, Required[Required[int]], names one record and is read as the one qualifier.
  • A mapping names each key schema once. close() of {str: anything, bytes: int, complement(str): anything} left two clauses over bytes, and its repr, {bytes: anything, bytes: int}, read back as dict[bytes, int], a smaller schema; open and close fold two clauses over one key schema into one over the join of their values, so it closes to dict[bytes, anything]. A dict display whose two keys build one key schema, {Validator(int): str, int: bytes}, is refused, as two keys that are one field name are.
  • A recursive body that never names the fixpoint is that body. recursive(lambda t: int) kept a definition no reference reaches and was not == to Validator(int); it is Validator(int), rendered as int.
  • Bare typing.Generic is refused. It is the base a generic class derives from and no type, and it built an isinstance test admitting an instance of every generic class.

Security

  • A meet holding a union twice beside a reference is not proved empty. A meet a recursive reference opens distributes each union it holds, and a branch kept the other copies of the union it came out of, so where the union stood twice -- bare, and inside another member -- a branch could be the meet already being decided, met again with no constructor between, and read as empty as a cycle under one is. So intersection(FRAC, union(None, NUMBER), JSON), a fractional number met with a nullable number and a recursive JSON universe, was answered is_empty() == True and "subset" of nothing though 0.5 is in it, in 0.0.18 through 0.0.20. A branch drops every copy of the member it distributes, which it is inside, and such a meet answers as its values do.
  • A complement walks a definition two members share once per room. A complement reads its inner walk with a stop as a third answer, and took no stop the walk kept for a definition at a value, so where every walk of a shared definition stops -- near the walk's bound, and past it -- each level below was walked once per path. complement(recursive(lambda t: union(int, [t], [union(t, str)]))) took 0.3 seconds to refuse a list nested 101 deep on the 0.0.17 wheel and 3 seconds at 102, a value its schema admits and that docs/guides/limits.md states the walk linear in, and a list nested 128 deep took longer than fifteen seconds on every release. The cost inside the bounds reached 0.0.17 through 0.0.20, and the one past them every release. A stop the inner walk kept answers one of its own kind with no more room, as the walk's own stops answer it: the complement costs what the walk costs, on every entry point.

0.0.20 - 2026-10-24

Three relations decided where they declined, one wrong subset proof withdrawn, and a crash and an unread bound repaired: three additions, one fix and three security fixes, and nothing removed or refused. A record against a union of records it splits across, a table of constants minus constants, and a mapping keyed by literals answer subset or not_subset where they answered undecided, and so does a relation over a byte pattern whose automaton fills the state bound. The security fixes are a literal proved below a predicate or a protocol by running its constant alone through it, though the literal holds every value of its type equal to the constant; a list read through a copy on CPython 3.10 and 3.11, which a garbage-collector finalizer emptying the list under the copy took down; and a constraint marker answering through a __getattribute__ of its own, whose bound went unread. The entries under Security name the releases each reached. Upgrade from any of them.

The walk reads the shapes a document is made of in fewer instructions, on the profiled wheels of every CPython the release builds, against 0.0.19 built from its tag: a mapping of one or two scalar clauses, as dict[str, int], 33% to 36% fewer with a global lock and 23% to 27% fewer on the free-threaded builds; a list of TypedDict records 12% to 13% fewer, and 8% on the free-threaded builds; a JSON array of records 2% fewer; and a list nested twenty-five deep 3% to 5% fewer with a global lock. That list counts 0.5% to 1% more on the free-threaded builds, in register moves the walk's layout makes, and reads fewer cycles there. On 3.10 and 3.11 a list read through its copy counts the three hundred or so instructions the copy spends holding the collector off: a thousand elements of one scalar kind 1.4% to 1.6% more, of a union of scalars and explained once refused under 1% more. Every other shape counts at most 0.15% more than 0.0.19, but the free-threaded builds' calls of under two thousand instructions, which the allocator moves by a few per cent either way.

Added

  • A table of constants minus constants is decided as the set it leaves. intersection(Literal[0, ..., n], complement(Literal[0]), ...) taking every member away is proved empty at any length, where the set representation declined from twenty-one members, and a table minus some of its constants is below a table holding the rest and refuted by one missing a constant left. The rules read it by lookup, as they read two tables: a constant is taken away by its pool position, and kept only where the bindings say it is a value apart from every table taken away.
  • A record is decided against a union of records it splits across. A record whose tag takes three literals is "subset" of the three records that each fix one, and "not_subset" of three where one also requires a key the subject leaves free, where that answered "undecided"; {"a": int, "c?": bool} is below a record requiring c beside one leaving it out. A record whose fields each take two types is decided against its corners up to six fields, where four declined, and seven decline on the decision budget. Read as emptiness, a record minus the records that cover it is empty, so an open record minus the record of each constant its key takes is proved empty at any length, where thirteen declined. The split is Castagna's backtrack-free rule for records (ICFP 2023), run by the rules rather than by building the difference.
  • A clause keyed by literals is read one constant at a time. Two mappings keyed by one literal are refuted under it at any depth: dict[Literal["a"], ...] forty levels deep over int is "not_subset" of the chain over str, where five levels answered "undecided". A record is refuted against a mapping keyed by literals on a str subclass's key equal to a field's name, which the field reads and the literal does not, so {"a": int} against dict[Literal["a"], int] answers "not_subset" where it answered "undecided"; and dict[Literal["a"], int] is below {"a?": int} by the rules, without the set representation.

Fixed

  • The widest pattern automaton the state bound admits is built. A byte pattern whose automaton gives every byte a class of its own reads 2,048 bytes a state, and the builder's limit was exactly MAX_STATES such rows, so the 4,094- and 4,095-state tables were refused by the 4,160 bytes the builder keeps beside its rows, and a relation over such a pattern answered undecided. The limit leaves room for them, and the state bound refuses a table at every width.

Security

  • A literal is proved below a predicate only where it is its constant alone. A literal holds every value of its constant's type equal to it, and the relations proved it below a schema by running the constant alone through it. So Literal[0.0] was answered subset of Annotated[float, lambda x: math.copysign(1.0, x) > 0], though -0.0 is in the first and not the second; Literal[Decimal("1.00")] was answered subset of a predicate requiring two decimal places, though Decimal("1.0") is in the first and not the second; and the literal of an instance whose __eq__ compares one attribute was answered subset of a protocol requiring another, which an equal instance carries otherwise. The answers were wrong in 0.0.1 through 0.0.19, the last in 0.0.16 through 0.0.19. Such a pair answers undecided. A literal of an int, a bool, a str, bytes, None, a nonzero float or an Enum member is its constant alone, and is decided as it was.
  • A list is copied for its walk with the collector held off before 3.12. On CPython 3.10 and 3.11 a list one test settles -- list[int], list[date], a list of literals or of tuples of scalars -- is read through a tuple copy of it where the copy pays, and allocating the tuple may run a collection inside the copy. A finalizer that collection ran which emptied or regrew the list left the copy reading memory the list had freed, and the process ended; the copy reached 0.0.10 through 0.0.19. The collector is held for the copy alone and its state given back, at about ten nanoseconds a list; 3.12 and later and PyPy copy as they did.
  • A marker answering through a lookup of its own is read through getattr. A constraint marker deriving from the annotated_types vocabulary that answers ge, max_length or another name through a __getattribute__ of its own carries the name neither on its type nor in its dictionary, which is where the frontend read it from, so Annotated[int, M()] with M answering ge=5 built int and accepted 0. The reading was wrong in 0.0.11 through 0.0.19. Such a marker is asked for every name, as one with a __getattr__ hook is, and builds Annotated[int, Ge(5)]; a marker read through the generic lookup is read as it was.

0.0.19 - 2026-10-20

A release of repairs: thirty-two fixes and eight security fixes, and nothing added or removed. Eight answers were wrong in a way SECURITY.md scopes as a vulnerability -- one wrong subset proof, six shapes that admitted a value outside the schema's set, and a walk exponential in a JSON document's depth -- and each entry under Security names the releases it reached. Upgrade from any of them.

The breaks are refusals, each of a spelling that built a validator reading another set than the one written: Required or NotRequired on a field of a dict literal, a type alias of an Annotated alias in metadata, a possessive quantifier or a spaced count in a pattern, a ... after an unpacked tuple or an unpacked tuple outside a tuple's arguments, a complex bound or step, and a Decimal step over a float base. A Regex of anything but text raises when the marker is made. Answers move where they were wrong: a complement reads its inner walk in Kleene's strong logic, close reads the clauses admitting every value as one, and a conjunct refutes beside one the rules decline. A repr reads back as the schema it came from but for the forms the API reference lists, a complement's expected names the set it excludes, a missing key is spelled as the path spells it, and a set reports its failures in an order the value fixes. Five costs that grew faster than a schema or a value -- a wide union's ==, a refused union's labels, a wide record over JSON, a long literal in a relation, and a chain of definitions -- grow no faster than it.

Fixed

  • A signal raised while a predicate's error is named propagates. The error's text was read through its formatter, which drops a signal its __str__ raises: validate reported a predicate_error reading <exception str() failed> and the interrupt was lost, and is_valid called the __str__ for a text it never reports. The text is read where a violation is recorded, and a signal is raised. A __repr__ returning a str subclass is read for the text it holds, rather than formatted through the subclass's __str__, which put <unprintable ...> in the summary.
  • A signal while the first validator reads the special forms is raised. An interrupt while typing.Never was first read was folded into the form's absence, which the process kept: every later Validator(typing.Never) was refused as a typing construct. The signal is raised, and the forms are read again by the next validator.
  • A relation raises a signal its reading of a class meets. A metaclass hook raising on the class's __eq__, or a __slots__ whose iteration raised, were folded into an answer, undecided or a verdict, and the signal was lost. They raise it, and an ordinary exception there declines the class's reading.
  • Pickling a ValidationError leaves the error as it was. The reduction deleted the error's internal failures from the instance being pickled, which a thread reading the error at the same moment could meet half done. It pickles a copy of the state.
  • An integer key past the interpreter's digit limit reaches the path as an integer. A key longer than sys.set_int_max_str_digits allows was named '<unrepresentable>', a string that indexes nothing. It is carried in hexadecimal, which the limit does not bind: path holds the key, and the message writes it [0x...].
  • A dict literal refuses Required and NotRequired on a field. A qualifier is read as the type it qualifies, so {"a": NotRequired[int]} built a record that requires a, and {"a?": Required[int]} one where a is optional, in silence. The literal says whether a key is required by its ? alone, so either qualifier on a field is refused, naming the key's spelling. ReadOnly is read as before.
  • instance_of(typing.Any) is the top whatever is imported. It was the top in a process that had loaded typing_extensions, which importing annotated_types does, and refused every value in one that had not. It is what Validator(typing.Any) is, on every release where Any is a class.
  • A dataclass field declared Annotated[Final[int], m] is read. The typing spec lets Annotated wrap a qualifier without changing it, and the field holds Annotated[int, m]; the class was refused as an unsupported typing.Final. Annotated[ClassVar[int], m] is still refused, in words that say why: it is a class variable to the typing spec and a field to dataclasses. A Protocol member declared either way is refused as one declared ClassVar or Final is.
  • A Regex marker pickles and copies. Unpickling restored its slot by setattr, which the immutable marker refuses, so neither pickle nor copy worked, and a schema holding one could not be sent to another process as a validator's own pickle refusal says to send it. It reduces to its pattern. A pattern that is not a str, such as Regex(123) or Regex(re.compile("x")), raises TypeError when the marker is made, rather than at the build, and comparing a marker with anything but a marker returns NotImplemented, so the other operand's __eq__ is asked.
  • A | ~A is the top where A is a union, and M & ~M the bottom where M is a meet. Construction flattens a union into the join that holds it, so no single member was A, and the fold declined: union(A, complement(A)) with A = union(int, str) printed int | str | complement(int | str) and compared unequal to anything, though it is decided equivalent. The fold reads the flattened members, so ==, hash and repr give the bounds. A join of many complements is folded in time near-linear in its width, where the pair check was quadratic.
  • A chain of recursive definitions is checked in time linear in its length. The contractivity check walked a definition once per path to it, so a chain whose every link names the one before it twice took 0.27 s at eighteen definitions and doubled per link; the 128 a validator may hold never finished. It enters each definition once.
  • A complement is below the complement of an empty refinement. complement(Annotated[str, Regex("x"), MaxLen(0)]) is the universe, since no string both matches x and has no characters, yet complement(Annotated[str, MaxLen(0), str.isdigit]) and the complement of a union of forty patterns were not proved below it in any release through 0.0.18. Two complements relate as their inner sets do the other way round, and there the empty refinement is the subject, whose emptiness the rule read without the set representation, the one reader of a pattern's shortest match. The rule asks it where the inner sets' relation declines, as the rule for a single complement does.
  • A constant prints whole in a repr. A constant past eighty characters was cut where an error message cuts a value, so Literal["x" * 100], Literal[10**100] and Annotated[int, Ge(10**90)] printed a syntax error where they could have read back. A constant prints its own repr in full, as a pattern and a field name already do; an int past the interpreter's digit limit, whose repr raises, prints <unrepresentable>.
  • A literal of a builtin's subclass is not printed as the builtin's literal. A literal admits its constant's own type, so Validator(S("a")), with S a subclass of str that writes no repr, refuses the str "a", yet it printed Literal['a'], which reads back as a schema admitting it, in 0.0.17 and 0.0.18; the same held for a subclass of int, float, complex and bytes. Where the constant's repr is the builtin's spelling of it, the literal prints as Literal[<S: 'a'>], a syntax error where it is read; a subclass whose repr spells it some other way prints by that repr.
  • A recursive schema's repr binds a name its body does not print. The back edge was bound to X, then Y, Z and T3, whatever the body printed, so recursive(lambda t: union(None, {"c": X, "n": t})) over a class X printed recursive(lambda X: union(None, {'c': X, 'n': X})), which reads the class back as the back edge and rebuilds a schema refusing {"c": X(), "n": None}, in 0.0.17 and 0.0.18. Each binder is the first spelling of its letter, X, X_1, X_2 and on, that no word of the render spells: a class's name, a constant's repr, or a name the interpreter reads as that spelling under NFKC normalization, such as a fullwidth X.
  • A validator's pickle refusal sends a reader to the forms repr cannot spell. It said repr rebuilds every form but a class or a predicate, and the API reference lists seven, two of which read back as a different schema; it names that list now. The boundaries page counts the two quiet forms where it counted one.
  • A key that reaches a record's field name is that field in every reading. A record read by scanning its entries, which is one beside a clause that reads its keys such as {"a": int, str: int}, took a key that is not an exact str for a field only where the key's own text named it, while the reading that asks the dict for the declared keys took it wherever d["a"] finds it. A key of another type that hashes and compares as "a", or a str that spells b and compares as a, was field a to {"a": int} and an undeclared key to {"a": int, str: int}, and validate against the second reported mutated_during_validation for a dict nothing had changed. Every reading resolves a key as the dict does. The soundness page adds the assumption the relations take for such a key: a key equal to a declared name is a string.
  • A set's failing elements are reported in an order the value fixes. They were ordered by the first failure's value and code alone, so two elements failing alike at different places, (1.5, 2) and (2, 1.5) against frozenset[tuple[int, int]], kept the order the interpreter handed them over: two equal frozensets reported in opposite orders and fail_fast kept different errors, and with string elements the order moved with PYTHONHASHSEED. They are ordered by everything each failure says: the value, the code, the path inside the element, and what it expected.
  • Two spellings of one schema fold to one when composed. Annotated[int, Ge(3), Ge(5)] and Annotated[int, Ge(5), Ge(3)] are one schema to ==, yet a union of the two validators kept both members, and union(a, complement(b)) stood unfolded for an a equal to b, where the same pair written as one annotation folds. The same held of two steps, of a map's literal keys, {Literal["x"]: int, Literal["y"]: str} against the keys written the other way round, and of either inside another schema. Composing interns one validator's constants into the other's pool, which can send two of them past each other, and a refinement's constraints and a map's clauses kept the order they held. Each set a composition renumbers is put back in the order construction gives it.
  • Two spellings that meet their recursive definitions in two orders are one schema. A validator numbers its recursive definitions in the order construction meets them, and == and hash read a reference by that number: union(r1, r2) and union(r2, r1), a record {"a": r1, "b": r2} against its fields written the other way round, and every schema holding either compared unequal and hashed apart, though is_equivalent called them one set and repr printed them alike, so the second spelling's repr read back as the first and not as itself. Composing the two kept a copy of each definition: ab | ba held four members, and ab | ~ba stood unfolded beside an ab equal to ba. In 0.0.10 through 0.0.18, where the algebra page gave the order of a set's members as no difference; 0.0.17 and 0.0.18 called the union two schemas, and the record was never one. Two PEP 695 aliases spelled alike were two definitions too, in 0.0.10 through 0.0.18: A | B held two members and did not equal A. A reference is read through to the definition it names, the two tables' definitions paired one to one in the order construction numbered them; composing finds a definition the target already holds under that pairing rather than appending a copy, and an alias definition the table already holds is that definition. A comparison that would need more than the depth or the steps the limits page states answers no, as it did.
  • One schema prints one way, whatever order its sets were written in. A union's literals printed in one order however they were written, and every other set printed in the order its constants or classes were first named: A | B and B | A, Annotated[int, Ge(3), Ge(5)] and the bounds the other way round, a map's literal keys and a meet's members were one schema to == and hash and two to repr. Within a set -- a union's or a meet's members, a refinement's markers, a map's clauses -- the members of one kind print in the order their renderings sort in, as a union's literals did, so a union of classes written Dog | Cat prints Cat | Dog. The members of different kinds keep the order they had, and every rendering reads back as the schema it came from.
  • A required key or a repeated element refutes beside a field the rules cannot read. {"a?": X} <= {"a": Y} answered undecided wherever the field's types were ones no rule reads, such as two predicate refinements, though {} is in the first and not the second; so did {"a?": int} against the same {"a": Y}, and [int, int, ...] against [Y, str, ...], which [1, 2] refutes. Required-ness was read only after the field's types were proved related, and a sequence's repeated element only after its prefix, though neither refutation rests on the other. Each is read beside it, and the three answer not_subset. A prefix no rule proves to hold a value, such as [X, int, ...], names no sequence for the repeated element to stand on, and stays undecided.
  • A complement's answer no longer depends on the order a value's parts are read in. A walk inside a complement that stopped -- at the depth bound, at a value holding itself, at a predicate that raised -- answered by whichever part it met first: complement(list[R]) refused [deep, "x"] and admitted ["x", deep], two equal dicts built in two orders answered apart, renaming a record's fields flipped the answer, and is_valid_json answered by key order. A stop in one branch of a union that another branch admitted was read by a complement above it as its own. The inner walk is read in Kleene's strong logic: a part that refuses refuses whatever a part beside it stopped on, a branch that admits admits whatever another stopped on, and only a walk where nothing decided is a stop, refused with its code. The change admits values under a complement and admits no value the complement's inner schema holds. A value that moved while it was read is refused with mutated_during_validation whatever the rest decided.
  • The clauses admitting every value close as one clause. close read each clause carrying anything on its own, as the region it frees where its keys were the complement of the others'. So {str: anything, complement(str): anything} closed to {}, as dict[anything, anything] does, while the same pair beside bytes: int, or the top split over int, complement(int) and complement(str), kept every clause and admitted every dict. Those clauses are one clause over the union of their keys: the part over keys another clause claims stays, and the rest is the region close refuses. The first shape closes as it did, the second to its bytes keys and the third to {}.
  • A bound or a step Python cannot apply is refused. Annotated[int, Ge(1j)], Annotated[int, MultipleOf(1j)] and Annotated[float, MultipleOf(Decimal("0.5"))] built validators that admitted nothing, and relation_to(nothing) answered undecided: Python raises on 1 >= 1j, on 4 % 1j and on 1.5 % Decimal("0.5"). A complex bound is refused with a ValueError, as a bound against nan is, and so is a complex step; a Decimal step over a float base is refused with a NotImplementedError, as a step over a base with no number is, and over int | float it narrows the integers. Because typing caches Annotated by equality, MultipleOf(2) built after MultipleOf(2 + 0j) arrives as it and is refused with it, where it admitted nothing before; the message says so.
  • A relation over a long Literal string or bytes answers at once. The set representation built a literal's automaton a state per byte and minimized it before the first product refused it as past the state bound, so Validator(Annotated[str, Regex("a*")]).relation_to(complement(Literal["a" * 1_000_000])) took a second to answer undecided. A literal past 4,094 bytes, a str counted in UTF-8, is refused before anything is built, and the same relation takes a tenth of a millisecond. So is a length bound over a list or a tuple past 4,094 elements, which built its automaton past the bound at 4,095 and 4,096. No answer moves.
  • == reads a wide union in one pass, whatever order it was written in. Equality matches a union's members as a set, and two spellings of one Literal written in different orders compared each member with every member left: 82 ms at four thousand members, four times as long at each doubling. A member is looked for only among the other side's members that hash alike, so the same comparison takes 0.4 ms. Two validators built alike match in place.
  • A refused union renders only the sixty-four labels its message names. Every member's label was rendered and the ones past the bound dropped, so a union of two thousand constants ran two thousand of their __repr__ methods for one refused value. Rendering stops at the bound, and a refused validate on that union takes 0.03 ms rather than 0.5.
  • A wide record whose clause reads keys checks a JSON object in one pass. is_valid_json against a record such as {"f0": int, ..., str: int} searched the document once per declared field, quadratic in the width: 580 ns a field at eight hundred fields against 70 at fifty. A record declaring more than eight fields resolves the document's keys through its plan, as a closed or an open record does, at about 40 ns a field whatever the width.
  • A complement's expected names the set it excludes. It named the kind of the schema it negates, so complement(Literal["admin"]) said not literal and complement(int | str) said not union, alone and as a union's branch. It reads not the literal 'admin' and not (int or str), naming its inner schema as a union names a branch.
  • Whether open or close keeps a field turns on that field alone. A field saying what its record already says of every key it does not name is dropped, and the field was read as written to decide whether to drop any and as opened to decide which. So with V the union dict[anything, anything] | complement({}), {"b?": V, anything: anything} closed to {"b?": anything}, and with "c?": anything beside it to {}, though the two admit the same dicts; and {"b?": intersection({}, complement( dict[anything, anything]))}, which admits what {} admits, opened to a record refusing the key b. A field is read once, as it stands with its own records opened: the first pair closes to {}, and the second opens to dict[anything, anything].
  • A missing key or attribute is spelled in expected as repr spells it. The label used Rust's escapes and double quotes, so a missing key "\x7f" read required key "\u{7f}" beside the path ['\x7f'], and every such label was quoted unlike the path and the other labels. It reads required key 'a' and attribute 'x', as the path quotes the name.

Security

  • A pattern over a base holding bytes is a set of strings in the relations. The set representation read Annotated[str | bytes, Regex("a*")] as the pattern's language over bytes as well, while the walk refuses every byte string. So Annotated[bytes, MaxLen(0)] was answered subset of it, though b"" is in the first and not the second; intersection(Literal[b"a"], complement(it)) was answered empty, though it admits b"a"; and its relation to str, and to Annotated[str, Regex("a*")], which it equals, was not_subset. The answers were wrong in 0.0.10 through 0.0.18. A pattern is read as its language over str and nothing else, as the walk reads it, and a base holding no string meets it in nothing. A pattern over a base wider than the word kinds, such as str | int, and a pattern no string matches, such as [^\s\S], are decided where they answered undecided.
  • A value is walked once per definition where two branches read it as one. recursive(lambda t: union(int, [t], [union(t, str)])) reads a list's element as t under both list branches, and each level of the value walked the level below once per branch, in every release through 0.0.18: validate_json took two seconds to refuse a document of 44 bytes on 0.0.17, and each further two levels multiplied it by four, on every entry point and for a value admitted by the second branch as well. The same held of a meet's members and of a map's clauses. A walk keeps what it answered for a definition at a value for the rest of the call, so the walk is linear in the value. A definition reaching a predicate, or a class whose metaclass is not type, is walked at each occurrence as before, since that code is called at each one; the limits page says so.
  • A tuple reads what an unpacked tuple splices into it as written there. tuple[int, *tuple[str, *tuple[bool, ...]]] was read as tuple[int, str, tuple[bool, ...]], whose third element is a tuple, where both static checkers read tuple[int, str, *tuple[bool, ...]], so (1, "a", (True,)) was admitted and (1, "a") refused, in 0.0.10 through 0.0.18; and a ... inside a splice was the literal Ellipsis. The spliced arguments are read as the tuple's own. A ... after a splice, tuple[*tuple[int, str], ...], which repeated the str, is refused, and so is an unpacked tuple outside a tuple's arguments: list[*tuple[int]] was a list of one-element tuples.
  • A type alias of an Annotated alias in metadata is refused as the alias is. Annotated[int, Pos] with Pos = Annotated[int, Gt(0)] is refused, since in metadata the alias annotates nothing, but the same alias written type Pos = Annotated[int, Gt(0)], or with TypeAliasType, was ignored and admitted -1 in 0.0.17 and 0.0.18, whose refinements page refuses such an alias. An alias in metadata is read through to what it names, applied to arguments or not, and refused the same way.
  • A pattern re reads as a different set is refused in two more forms. A + after a quantifier is possessive to re from 3.11 and a second repetition here, so a?+ admitted "aa", which re.fullmatch refuses; and this engine reads a{1, 3}, whitespace in its braces, as a count, where re reads it as the text "a{1, 3}", so it admitted "a". Every release through 0.0.18 read both forms so. Both raise a ValueError naming the reading, as the class-set operators do.
  • A Protocol member declared with functools.cached_property holds what its function returns. It was read as a value, holding anything, so @cached_property def size(self) -> int admitted an object whose size is a string, in 0.0.16 through 0.0.18; before 0.0.16 a protocol was the values isinstance admits, as its guide said. It is read as a property is, through its function's return annotation.
  • close after open refuses again what open freed, and no more. Opening folds the freed region into a clause admitting every value, and closing kept that clause whole wherever its key was not exactly the region: dict[C, Any] over a class, {int: Any, str: int}, and dict[int | str, Any] each round-tripped to a schema admitting every key, in 0.0.12 through 0.0.18, where the guide says the round trip is at most close. Closing takes out the region and keeps the keys the clause claims, so the first two round-trip exactly; where the complement law folds the opened key to every key, the round trip is a smaller schema than close. And dict[Any, Any] relates to dict[Literal["a", "b"], Any] opened as subset, where it answered undecided.
  • A complement admits no member at the walk's bound. A union of scalars that sat at the walk's depth bound, as a record's field or a mapping's value, answered its scalar branches false without saying the walk had stopped, and a complement over the schema read that as the value being outside it: complement(recursive(lambda t: {"a?": {"x": {"y": t}}, "b": int | str})) admitted every value nested past the bound, in every release through 0.0.18, and from 0.0.10 a value the schema admits too. A scalar branch at the bound stops, as a scalar does anywhere else, and the complement refuses the value with recursion_limit.

0.0.18 - 2026-10-12

A release with two breaks. Validator.simplify is removed, after warning through eight releases, and a callable where a schema goes is refused, where it was read as the constant it is. Two additions, one change, one removal and six fixes.

A schema is built in the lattice normal form, so repr and == read the reduction simplify promised, and the relations decide what it folded beyond the laws. A callable where a schema goes is refused rather than read as a constant, and the refusal names both spellings that were meant. Two readings are new: a generic type alias applied to its arguments, and a meet with a recursive reference, decided. Relations between maps decide where they answered undecided: one is refuted on a key the other reads one way, and a key written as a complement of kinds is read as the other kinds. The frontend refuses an annotation at the node bound as it reads, in milliseconds where a shared part built for over a minute; a validator built inside another build counts only itself; deprecated and annotated_types.Unit in metadata are ignored; and a product split across a wide union is held to the relation's depth bound.

Added

  • A meet with a recursive reference is decided. For chain = recursive(lambda t: union(None, {"next": t})), intersection(chain, {"next": int}) is empty and intersection(chain, {"next": {"next": None}}) is not, where both answered "undecided". The reference is unfolded into the meet, a key that names it asks the meet of its types again, and a meet met again while it is decided reads as empty, under a goal of the meet's own rather than the reference's. A reference written inside a key's union, recursive(lambda t: {"next": union(t, None)}), decides the same way.
  • A generic type alias is read applied to its arguments. Pair[int] from type Pair[T] = tuple[T, T] was refused as an unsupported form with origin Pair; it reads as tuple[int, int], the body with the arguments in place of its parameters, for a typing_extensions.TypeAliasType too. A parameter given no argument takes its default, and an alias whose every parameter has one reads bare. A recursive generic alias, type Tree[T] = T | list[Tree[T]], ties one fixpoint per list of arguments. A surplus or a missing argument, a bare alias whose parameter has no default, a ParamSpec or TypeVarTuple parameter, and an alias applying itself to an argument that nests its own parameter each raise NotImplementedError by the alias's name. A parameter's bound is a checker's to hold and is not read.

Changed

  • A callable where a schema goes is refused. Validator(fn), intersection(Record, fn), [fn], {"key": fn} and list[fn] read a function, a bound method, a partial or a callable object as the constant it is, a set holding that one object -- so a meet meant to narrow a record by a check admitted nothing, and the decisions, which leave a meet with a literal undecided, could not say so. Each raises NotImplementedError naming the two spellings that were meant: Annotated[T, fn] for the values of T the callable accepts, and Literal[fn] for the object itself, which reads as the constant. Annotated metadata reads a callable as a predicate, as it did, and a class is read as the class it is.

Removed

  • Validator.simplify. It warned through eight releases, from 0.0.10. A schema is built in the lattice normal form, so repr already shows the reduction it promised and == compares it; what it folded beyond the laws -- a meet of disjoint kinds, a join covering every region -- is a decision the relations make. Write intersection(int, str).is_empty() rather than repr(intersection(int, str).simplify()) == "nothing", and union(int, complement(bool), Validator(1)).is_equivalent(object) for a join that covers every value.

Fixed

  • A validator built inside another build is measured on its own. An annotation the frontend evaluates can construct a Validator -- a predicate built in a field's Annotated metadata -- and that build started from the depth of the build around it, so a schema within the bounds was refused as nested too deep. Each build begun from the API counts only itself. The refusal past the depth bound names the bound it passed.
  • A map is refuted on a key the other reads one way. A relation between two maps was left undecided wherever a refutation needed a key the subject's clause admits: {str: int}.open() against {str: int}, dict and {str: bytes} against a recursive JSON schema, {tuple: int} against {str: int}, and {"a": str} against {str: int}.open() all answered undecided, though {7: "x"}, {7: 1}, {"a": b""}, {(): 1} and {"a": ""} refute them. The rules read a key schema by whole kinds -- one that holds every value of a kind, or none -- and refute where the supertype reads such a kind through one clause or none: an entry under a plain key of that kind is in the subject and outside the supertype. A key type whose plain values are unhashable, such as list, tuple[list[int]] or a class whose instances are unhashable, holds a key only through a subclass that hashes, and is never refuted; two clauses reading one kind decline. A nested dict[str, ...] is refuted at any depth, where five levels deep answered undecided.
  • A map keyed by a complement of kinds is decided. A relation about a map whose key was a complement -- the clause open writes on a mapping -- was left to the clause rules, and a pair they could not read answered undecided: a plain class against {complement(str): int} or {str: int}.open(), dict against {str: Any, complement(str): Any}, and {complement(bool): int} against {complement(int): int, int: int}. The set representation reads a complement of whole kinds as the other kinds, a class instance among them -- so {complement(str): int} is outside the map keyed by every listed kind on {object(): 1} -- and a tuple or frozenset key as its kind. None and bool keep their finite keys: {None: int | str} opened is below {None: int} opened or {None: str} opened, and the same over bool is refuted on {True: 1, False: "x"}. A key holding part of a kind -- the complement of a literal, tuple[int, ...], a class -- declines, and the decidability page lists it.
  • An annotation is refused at the node bound as it is read. Validator(spec) built the whole schema an annotation names before the node bound was asked, and a class, an alias or any annotation object is built once per place it is named -- so a part shared through several levels built a tree that multiplies with each. Four TypedDicts a level, each holding the union of the level below, took 75 seconds and 6 GB to be refused at twelve levels. The frontend holds what it has built to the bound as it reads and refuses a step past it, in milliseconds, with the ValueError it raised before. A schema within the bound builds as it did; a part a fold drops still counts toward the union that dropped it.
  • deprecated and Unit in metadata are ignored. Annotated[int, typing_extensions.deprecated("...")] refused every value from Python 3.13, where typing_extensions re-exports the standard library's decorator: its class lives in warnings, which the frontend did not read as a typing form, so it was called as a predicate and raised. Annotated[float, annotated_types.Unit("m")] was refused as a constraint valgebra does not check, though Unit names what a number is measured in and excludes no value. Both are ignored, as a typing form and the documentation marker are; a group yielding Unit beside a bound reads as the bound, and Timezone is still refused. A decorator function in metadata, such as dataclasses.dataclass or typing.final, cannot be told from a predicate and is called, which the refinements page states.

  • A product split across a wide union is held to the depth bound. A relation such as tuple[int, int] against a union of hundreds of tuple[Literal[i], int] narrows the product by one branch a level, and those levels went uncounted by the bound that keeps a relation inside a 1 MiB thread, so a goal asked at the bottom of the chain could open its whole depth on top of them. Each branch is a level of that bound, and past it the relation answers "undecided".

0.0.17 - 2026-10-06

A correctness release: two additions, three changes and eighteen fixes.

Several answers change, each because the old one was wrong. Relations over patterns and literals that were proved are refuted: a pattern's set is every string it matches whole, and a literal is its constant at its exact type. A value nested past 384 levels is refused where 512 were walked, so the walk fits the 1 MiB stack the shipped wheels are measured on. A complement refuses a value its inner walk stopped on rather than admitting it. A marker that is not annotated_types' is ignored whole, a typing form in metadata is no longer called as a predicate, and four forms that built quietly are refused. A union of records told apart by a tag, and validate on a refused one, are linear in the value. Two readings are new: instance_of(C), the instances of a class whatever their fields hold, which a dataclass or a NamedTuple had no spelling for; and a Final[T] field of a dataclass, read as T where the class was refused.

Added

  • instance_of(C) is the instances of a class, and reads nothing it declares. Validator(C) checks each field of a dataclass or a NamedTuple; instance_of(C) admits every instance, an ill-typed or unset field included, which is the set isinstance answers. It is the class atom the algebra already held, with a spelling: Validator(C) is proved below it, and a dataclass whose declaration has no reading -- a bare Final field, a type parameter, a self-reference -- has this one. For a class that declares nothing it is Validator(C). A TypedDict and a Protocol have no instances of their own and are refused, as isinstance refuses them. The atom of a declaring class prints as instance_of(C).
  • A Final[T] field of a dataclass is a field holding a T. The typing spec makes x: Final[int] in a dataclass body a field x that __init__ sets and nothing assigns after, and a class carrying one was refused whole. Final says the name is not rebound, which is not a question about the value, so the field is read as the type it wraps. A bare Final, whose type a checker infers from the default, is still refused.

Changed

  • A union's report names the record branch that admitted the most. Of a union's record branches, the one explained is the one whose check admitted the most fields before refusing the value -- the fields decided by their own value read first -- then one refused inside a field's nested value, the earliest on a tie, where it was the earliest whose first failure lay deepest. A value tagged for one record of a union is reported against that record rather than against the first one: {"t": "y", "z": 1.5} against {"t": Literal["x"], "z": int} | {"t": Literal["y"], "z": str} reports z, not the tag.
  • The walk holds at most 384 levels open, from 512. The shipped wheels are built with profile-guided optimization, whose frames are four to five times the plain build's, and the deepest walk at 512 levels needed 1.5 MiB of stack where the limits page promised 512 KiB. At 384 it needs under 896 KiB, and the page says 1 MiB, the least stack any thread CPython creates has. The smallest recursive body, recursive(lambda t: union(int, [t])), is still walked to the unfolding bound of 128, so no answer for it changes; a deeper body meets the walk's bound sooner -- {"a": {"b": {"c": T}}} | int is refused with recursion_limit from 77 unfoldings, where it was 102.
  • A constraint is read off the annotated_types vocabulary alone. A marker carrying a ge, a min_length, a pattern or a func was read by those names whichever library wrote it, and another library means its own thing by them: msgspec's Meta(pattern="a+", max_length=3) became a whole-string pattern with its length dropped, where msgspec searches and keeps the length; Meta(ge=0) was refused for the pattern it leaves unset; pydantic's AfterValidator(f) was called as a predicate and judged a value by the truth of what f returned. A marker whose class derives from the vocabulary is read for the vocabulary's names, a pattern off Regex and a compiled re.Pattern, a func off Predicate, and any other marker is its own library's metadata and is ignored, as pydantic and msgspec ignore each other's. A GroupedMetadata is unpacked before anything is read off it: pydantic's StringConstraints contributes its lengths, and its pattern, which pydantic searches with, is ignored. A class written bare is refused only where it is the vocabulary's own or a pattern marker's, and any other is ignored.

Fixed

  • A pattern's set is every string it matches whole. The relations read a Regex as the strings a search reports first, which is fewer than it matches: an alternation whose earlier branch is a prefix of a later one, an empty first branch, and a lazy repetition each lost the matches ranked below the first. Regex("http|https") was proved below Literal["http"] and equivalent to it, Regex("ab") was refuted below Regex("a|ab"), and the meet of Regex("foo|foobar") with Literal["foobar"] was decided empty. Membership was right throughout: the walk matches a pattern whole, and the relations read the same set.
  • A field two clauses cover together is not refuted. A record field the supertype does not name is read through the supertype's catch-all clauses, and the field was refuted where each clause refused its type alone, though the clauses together admit every value of it: {"f": int | str} was not_subset of {str: int, Any: str}, which holds it. Each clause's refusal stands on a value of its own; with two or more clauses the relation goes to the set representation, which decides this one subset.
  • A set's refutation stands on members a Python set keeps apart. A set of two element types is outside the union of the sets of each by a set holding one member of each, and a Python set holds no two members that compare equal. Where the two were one number in two kinds the refutation stood on no value: set[Literal[1, True]] was not_subset of set[Literal[1]] | set[Literal[True]], though {1, True} is {1} and every set of it is in one of the two, and 1 with 1.0 read the same way. Those pairs are undecided; every other refutation of this shape stands.
  • A literal is its constant at its exact type. The relations read Literal[5] as every int equal to 5, an int subclass's included, where the walk admits the exact int alone: Annotated[int, Ge(5), Le(5)] was proved equivalent to Literal[5], Annotated[str, Regex("a")] below Literal["a"], and the meet of Literal[5] with an int subclass was not proved empty. An IntEnum member equal to 5 is in the bound and not in the literal, and those pairs are refuted or decided the other way. Membership was right throughout.
  • A record is not proved below a mapping keyed by literals. {"a": int} was subset of dict[Literal["a"], int], and {MyStr("a"): 1} is in the record and not in the mapping: a field reads every key equal to its name, and a literal key is the exact str. A proof that stands on a literal key subtracted from a dict a field or a kind's part can key is undecided; a subject keyed by literals alone decides, and every refutation stands.
  • A complement refuses a value its inner walk stopped on. A walk that stops -- past the depth bound, at a value that contains itself, at a value that changes while it is read, at a predicate that raises -- answers no as a non-member does, and complement admitted every such value: [T] & ~T, which the relations prove empty for T = recursive(lambda t: [t]), admitted a list one level past the bound through is_valid, validate, ensure, is_valid_json and load, and so did the documented deny-list shape intersection(X, complement(P)) for a predicate with a bug. The complement refuses the value with the code the inner walk stopped with.
  • is_valid and validate agree at the depth bound. A union of literals is answered from a table when a value is only being checked and branch by branch when it is explained, and the table answered without the level a branch takes: a value whose union of literals sat one level past the bound was a member to is_valid and in and refused with recursion_limit by validate and ensure. Both refuse it.
  • A union of records told apart by a tag is linear in the value. Fields are read sorted by name, so a tag such as type beside a recursive left was read after the child, and each branch the tag refused walked the whole child first: is_valid on a valid value of four such branches took a second at ten levels and did not return at twenty, on the object and the JSON path alike. The check reads a field decided by its own value first.
  • validate on a refused union of records is linear in the value. Each refused record branch was explained in full, its recursive field included, so the default report on a refused chain of such a union doubled per level: a third of a second at eighteen levels of a three-hundred-byte value. One record branch is explained.
  • A union runs no __repr__ of a value it admits. A branch before the one that matched was explained -- a named tuple, a list, a set, a tuple, a meet or a complement -- and explaining it rendered the value: a __repr__ that raised MemoryError made validate raise for a member, and a 20,000-element member of list[int] | list[Slow] ran 20,000 of them. 0.0.16 settled this for record and class branches; the union is decided before any branch is explained.
  • A relation does not overflow the stack. Two recursive schemas whose bodies nest 100 and 99 lists around the back edge, or a chain of 96 definitions each a hundred one-tuples deep, made relation_to, is_subtype_of, is_equivalent and is_empty recurse until the process died, on the main thread as on any other: the work budget counts steps, and each level is a few of them. A relation holds at most 512 levels of its own recursion and answers undecided past them.
  • A JSON object's keys cannot be chosen to collide. The undeclared keys of a parsed object wider than eight entries were collected into a table hashed with an unseeded hash, whose collisions are the same in every process: a document of 20,000 keys computed to collide, 0.74 MB, took half a second against dict[str, int] where as many ordinary keys took 2 ms, four times as long for each doubling. The table is keyed per process, and the keys are covered in the document's order. An ordinary wide object reads 9% to 14% fewer instructions than before.
  • A qualifier inside Annotated says whether a TypedDict key is required. Annotated[NotRequired[int], Ge(0)] was read from the class's key sets, which under from __future__ import annotations CPython computes from strings: the key was required, and Annotated[Required[int], Ge(0)] in a total=False class optional.
  • A typing form is refused where a constant or a type argument is read. Literal[list[int]] built list[int], Literal[NewType("U", int)] built int, and on 3.10 Literal[Any] built Any; NewType("N", "int") and TypeAliasType("A", "int") built the literal 'int'; InitVar[int] built a literal of the form object; and below 3.13 a bare Annotated built a class test no value passes. Each is refused, naming the spelling that was meant.
  • \<, \> and \b{...} are refused in a pattern. They are word-boundary assertions in this engine and literal characters to re, so Regex(r"\<b\>") admitted "b" and refused "<b>".
  • A union holding a record prints as the call that builds it. union({'a': int}, {'b': str}) printed as {'a': int} | {'b': str}, which Python reads as a dict merge, the one record {'a': int, 'b': str}, and a union beside a list display printed an expression that raises TypeError. Both print as union(...). A record's key is spelled by Python's own repr, where a name carrying a quote printed as two fields.
  • open and close reach the record a mapping maps to. dict[str, {'b': int}] opened freed the key-types beside str and left the record every str key maps to closed; that record is opened with the rest, and closed with it. The pages called close a function of the set, and it rewrites the term as open does: a meet of two open records and the open record of their fields are one set, and the meet closes to nothing. The pages say so now, and that a second open gives the set the first did and may respell it.
  • A typing form in metadata is not a predicate. A callable in Annotated metadata is a predicate, and every typing form is callable: calling one with a value built something, and its truth was the verdict. Annotated[float, at.IsFinite[float]] admitted infinity and refused zero, Annotated[str, list[int]] refused the empty string, and a bare at.IsFinite raised for every value. A typing form is metadata this frontend does not recognize, and is ignored; an Annotated alias carrying a marker this frontend reads is refused, naming the spelling that was meant.

0.0.16 - 2026-10-04

A protocol and correctness release: three entries, one change and two fixes.

A Protocol is the record of the members it declares, decorated or not, where it was an isinstance check that held only where @runtime_checkable sat on the class itself, and it relates to other schemas as a record. Six things a runtime-checkable protocol did break, and the entry below names each. A refutation about a class stands on an instance that can carry its fields, so a pair refuted on a value that may not exist is undecided. And validate explains a union's record and class branches only for a value the union refuses, so a member of such a union is checked without running any __repr__.

Beside the entries, the release carries performance work on validating a value, on building a validator and on relations between validators. No answer changes.

Changed

  • A Protocol is the record of the members it declares, decorated or not. A protocol compiled to an isinstance check against the class, and only where @runtime_checkable was applied to the class itself; any other protocol was refused. It denotes the values carrying every member it declares, each read by getattr: an annotated member holds a value of its type, a method or special method holds a callable, and a property holds what its getter's return annotation names.

Six things a runtime-checkable protocol did break. A member present with a value outside its type is refused, where isinstance admitted it. An instance of a class naming the protocol among its bases, with a data member never assigned, is refused. A member a __getattr__ hook serves, a getter that raises and an unassigned slot answer alike on every release, where isinstance answered them one way on 3.10 and 3.11 and the other way from 3.12. A generic runtime-checkable protocol -- typing.SupportsAbs and typing.SupportsRound among them -- and one declaring a member ClassVar or Final built in 0.0.15 and are refused now, each with the reason. A value refused reports the member it lacks or holds wrongly: missing_attribute at the member's path, expecting attribute "__int__", where it was instance_type at the root expecting the protocol's name, so a caller branching on the code reads another one. And repr prints the record of the members, object(x=int), where it printed the protocol's name. A protocol without the decorator, or inheriting its mark from a base, builds where it was refused, and the bare Protocol base is refused, with the reason.

A protocol relates as a record: a dataclass declaring its members, each at least as narrowly, is below it, and a protocol with more members is below one with fewer. A record is not read as satisfied by an exact int, str or other builtin value, whose attributes are its type's, so a builtin kind against a protocol declines where the witness would be such a value.

Fixed

  • A relation about a class and its fields stands on an instance that can carry them. A dataclass is its class met with a record of its fields, and a refutation about one -- not_subset against a kind or another class -- stands on a direct instance of the class holding a value in each field. That instance was assumed whatever the class defines. Where a field's name is a property or another data descriptor on the class, or the class defines __getattribute__, what the instance holds there is the answer of code, and the pair was refuted on a value that may not exist; it is undecided. A class whose instances have no __dict__, a name the class body defines and a slot are read the same way, each for what a direct instance can hold.
  • validate explains a union's record and class branches only for a value the union refuses. A record branch -- a TypedDict, a dict schema, a mapping -- and a class branch, a dataclass among them, were explained as each was decided, and the report was dropped when a later branch admitted the value: validate ran the value's __repr__, or a field's, once for each such branch before the one that matched, a predicate under one ran a second time, and a repr raising MemoryError made it raise for a member. A record branch's explaining pass waits until no branch has admitted the value, and a class branch is decided by its instance test, a dataclass's where its metaclass is type. validate on a member of a union of records or of dataclasses costs a fifth of the instructions it cost, close to what is_valid costs; the report for a value no branch admits is unchanged.

0.0.15 - 2026-10-01

A correctness release: thirty-three entries, all fixes.

Four relations answered wrongly and two declined. A step of -2**63 was read as the set holding zero, a pair of float bounds as reals with a real between them, a step dividing another as an inclusion across kinds of number % does not keep, and one dict key as witnessing two clauses of a union. A record below the complement of two records, and a union of pattern refinements below the complement of an empty one, are decided where they were undecided.

The frontend reads more of what the typing spec writes. A validator in Annotated metadata narrows the schema rather than being ignored, a typing_extensions form reads as its typing one, and a TypedDict built by typing_extensions or inheriting from a closed one admits the extra keys its declaration says. A marker class written without its parentheses, a bare TypedDict or NamedTuple, a pattern that parses only once anchored and a space or # in a verbose character class are refused, where each built a schema for another set or failed for another reason.

A fatal signal -- an interrupt or a MemoryError -- raised in code the library calls propagates from every site that read it as an ordinary answer: a key's __eq__, a type's metaclass, the __repr__ of any part of a message, a predicate, bound or step that building or a relation asks, and the comparison, hash and repr of a constant a validator holds.

Three fixes are about a process rather than an answer. Building the first validator on Python 3.15 could wait for good beside a thread importing annotationlib, and on PyPy a tuple subclass yielding fewer items than it holds crashed validate, and a dict whose key a predicate swapped mid-scan took the interpreter down.

The rest are the walk and its reports. A list subclass is judged by what it holds on every interpreter, as a tuple or dict subclass is on PyPy, and a length bound is read before the elements it bounds. A report names an intersection branch by its members, quotes a key that is not a bare name in its location, spells a pattern as its Python literal, names each key of a path by what it holds, and under fail_fast walks each union branch only to its first failure.

Fixed

  • A TypedDict built by typing_extensions is open unless it says otherwise. PEP 728 writes "no extra_items given" with a sentinel, and typing_extensions carries its own, a different object from typing's before Python 3.15. On 3.10 to 3.14 its open default, and closed=False, were read as a record whose only admitted extra value was that sentinel, so every extra key the class allows was refused. And on every release extra_items=None, which gives the extra values the type None, was read as no marker and admitted any extra value. Each spelling is read as it says, whichever implementation built the class.
  • A validator in Annotated metadata narrows the schema. Annotated[int, v] for a compiled validator v was read as int: the validator was taken for metadata nothing recognizes and ignored, so a class field written to refuse what v refuses admitted every int. It is the meet of the refined base and v, the set intersection(int, v) builds, whether the validator is written on its own, beside other markers or inside a grouped one; a static checker reads the field as int.
  • A union's report names an intersection branch by what it admits. The branch was listed as the word intersection, which names no set; it lists each member joined with and, as in one of: str, int and not bool, with a member that is itself a union in parentheses.
  • Refusing a union under fail_fast costs a fail-fast walk of each branch. The report chose the closest branch by the deepest failure anywhere in it, which walked every branch whole even under fail_fast: a 100,000-element list refused inside a union branch took 350 ms where is_valid took none. The closest branch is the one whose first failure lies deepest, which a walk stopped there has measured, so under fail_fast each branch stops at its first failure, and the full report chooses the same branch. Where one branch fails shallowly and again deeper inside, the other branch may be the one reported.
  • A fatal signal raised by a key's __eq__ or a type's metaclass propagates. An interrupt or a MemoryError raised while the walk looked a record's field up by name, resolved a str subclass key to a field, asked a tuple or set subclass's type for its __len__ or __iter__, copied a value through its storage or turned a JSON value into a Python object was read as a failed probe, so the check answered and the signal was lost. Each is re-raised, as one raised by a predicate is.
  • A list subclass is judged by what it holds on every interpreter. Below Python 3.14, and on free-threaded builds, a list of scalars was read through a copy that iterates it, so a subclass whose __iter__ yields something other than what it holds was judged by what it yields there and by what it holds on 3.14. Only an exact list is copied.
  • A marker class is refused with the spelling that was meant. Annotated[int, at.Ge], a marker written without its parentheses, was ignored as unrecognized metadata, so the schema was int and admitted every value the bound was written to exclude. A class whose instances would be read or refused as a constraint -- one from annotated_types, or one carrying a name a constraint is read through, such as ge or pattern -- is refused with a message naming Ge(...). Any other class, such as a unit or an enumeration, is ignored as before.
  • A length bound is read before the elements it bounds. Annotated[list[int], MaxLen(3)] walked every element of a longer list before reading its length, so a list of a million elements cost a million checks to refuse, and one holding a wrong element was reported for the element. On a list, tuple, set, frozenset or dict, MinLen and MaxLen are read once the value is of the base's kind and before any element, where a fixed shape reads its length: the list is refused with too_long alone. Membership is unchanged.
  • An opened map lists its clauses as the same clauses written out do. open() folds the key region no clause claims into the clause carrying the same value, and kept that clause where it stood, so Validator({int: object, str: int}).open() rendered its clauses in another order than the same clauses written out, though the two compare equal. The opened list takes the order every spelling of it gets.
  • A step of -2**63 is not read as zero alone. Annotated[int, MultipleOf(-2**63)] admits -2**63 and 2**63, and its steps were read as the set {0}, so it was proved below Annotated[int, Ge(0)] and proved empty beside Gt(0). The step's magnitude is past the integer set's period, as every step that large is, and a relation that turns on it declines.
  • No float lies between a float and the next one. A set of floats was read as a set of reals, so Annotated[float, Gt(1.0)] and Annotated[float, Ge(math.nextafter(1.0, math.inf))] were proved to differ though they admit the same floats, and a pair of bounds with no float between them was read as inhabited. An open bound is held as the closed one at its neighboring float, and both relations are decided exactly.
  • A step dividing another is not read across kinds of number. Annotated[int, MultipleOf(6.0)] was proved below Annotated[int, MultipleOf(3)] because 3 divides 6.0, and 2**53 + 5 is in the first alone: % reads the int as the float nearest it. A step past 2**53 over float, and a Decimal or object base, met the same proof and the same counterexamples. The inclusion is proved where % reads a value and both steps as one kind of number, and declines elsewhere. An int step against a float step over float is decided, by the operator's reflected form.
  • One dict key cannot witness two clauses of a union. The closed record {"a": int | str} was reported not_subset of {str: ~int} | {str: ~str}, though {"a": 1} is in the second and {"a": "x"} in the first. Each "some key maps into this" constraint of a map was read on its own, so two of them found the one key a and asked it for an int and a str at once. The constraints no fresh key can meet are read together, and so are the two keys of bool and the one of None, which a constraint can run out of.
  • A pattern that parses only once anchored is refused. Regex("a)|(b") does not parse, and wrapped for a whole-string match it closes the anchors' group and opens one they close, so it compiled into an alternation that escaped both anchors and admitted "xxb". A pattern is parsed on its own before it is anchored, and one that does not parse raises the build's invalid regular expression error.
  • A fatal signal from any part of a message propagates. A KeyboardInterrupt from the __repr__ of the constant a literal names, of a bound or step a value missed, of a value a constraint refused, of a key the path names by its repr, or from a metaclass answering __name__, read as <unrepresentable> in a ValidationError. The value refused by its kind was the one site that carried it out. Every part of a message the walk renders raises the signal out of validate.
  • An object carrying __metadata__ and no __origin__ is a value. The build read any object with __metadata__ as Annotated and asked it for __origin__, so an object without one failed with a bare AttributeError, a type the build is documented never to raise. It is read as every other object is, as the literal of itself.
  • A typing_extensions spelling reads as its typing one. Before the release that adds a form to typing, typing_extensions defines it with an object of its own, and the frontend asked typing alone. On 3.10 typing_extensions.Never read as a literal of the form object and admitted it, Any read as a class nothing is an instance of, Self and LiteralString read as literals, and Required, NotRequired, ReadOnly and Unpack were refused, so a TypedDict using them did not build. Before 3.15 an alias built with typing_extensions.TypeAliasType read as a literal of the alias. Each reads as its typing spelling does.
  • A bare TypedDict or NamedTuple is refused. Each is a function or a form at runtime, and Validator(NamedTuple) read it as a literal of that one object, a schema that admitted nothing a caller has. A checker reads NamedTuple as every named tuple class and refuses TypedDict as a type. Both, from typing or typing_extensions, raise NotImplementedError naming the class to pass instead.
  • A TypedDict subclass inherits what its base says about unnamed keys. The typing spec's open default holds "except when inheriting from another TypedDict that is not open", and the runtime writes closed and extra_items only on the class that gave them. A subclass of a closed=True or extra_items=T TypedDict read as open and admitted any extra key. It reads what its nearest base states, and a class that says closed=False itself stays open.
  • A space or a # inside a character class under verbose mode is refused. re.VERBOSE keeps both as members there, and this engine ignores the space and starts a comment at the #. re.compile("[ a]", re.VERBOSE) as a marker admitted no space where re admits one, and [#a] failed with "unclosed character class". Under re.VERBOSE, (?x) or (?x:...), either character in a class raises a ValueError naming it and the escape to write instead.
  • The unsupported-form refusal names every subscripted form it reads. It ended "supported: list, set, dict, tuple, Union, Optional, Literal, Callable", which left out frozenset, Annotated and the TypedDict qualifiers, all of which build. The list names each of them.
  • A tuple or dict subclass is read for what it holds on PyPy. PyPy's C API reads a subclass through the methods it overrides. A tuple subclass whose __iter__ yields fewer items than it holds crashed validate and ensure, and is_valid answered about items it does not hold; a dict subclass overriding __len__ was refused by a closed record it belongs to, and one overriding __getitem__ by dict[str, int]. Such a value is copied through the base type's own methods and the copy is walked, which reads what CPython read all along.
  • An error path names each key by what it holds. A big integer key was spelled by its own __str__, so an int subclass answering "7" named another key, and one raising KeyboardInterrupt lost the signal and was spelled as a string. Its digits are read from its storage, as a small integer's value is. A str key holding a lone surrogate read as the empty string and named the entry d[""] is; it appears as its repr, like any key a path cannot spell.
  • A signal an element's __repr__ raises once propagates from a summary. A container is summarized through reprlib, which lets a KeyboardInterrupt through; the plain repr behind it then ran the element again and read its answer as the summary, so a signal delivered once, as an interrupt is, became a ValidationError.
  • Building a validator and asking a relation carry a fatal signal out. A relation runs user code -- a predicate or an __eq__ it probes a literal with, a bound's comparison -- and read a fatal signal raised there as undecided, as False from is_empty, or, through a literal, as the verdict not_subset. Building read one raised by a marker's attributes, a bound's conversion or a step's comparison with zero as the fallback an ordinary exception gets, and an interrupted isinstance(bound, Number) as a bound with no order, refused with a NotImplementedError about the wrong cause. Each raises the signal.
  • validate explains no union branch that refuses a value by its kind. Such a branch fails at the union's own location, where a report reads only the union's label, and explaining it summarized the value: validate ran a member's __repr__ once for each branch before the one that matched, and a repr raising MemoryError made it raise for a member. The branch is decided without being explained; the report for a value no branch admits is unchanged.
  • A dict whose key is swapped mid-scan is answered on PyPy. A predicate or a key hook replacing one key with another at the same size, while dict[str, T] or a record with extra_items scanned the dict, made PyPy's C API fail fatally and took the process down. The scan reads a copy there, and the change is the one the walk does not see, as on CPython.
  • A key that is not a bare name is quoted in a message's location. The location wrote every string key as itself, so the key "a.b" read as the path a then b, "[0]" as the index 0 and the empty key as nothing, and a key holding a newline split message, and its line of str(exc), in two. Such a key is written as a subscript of its Python literal, at ['a.b']:; the structured path is unchanged.
  • A pattern's and a depth bound's expected name the set a value missed. A pattern was spelled in Rust's escaping, a string matching "\\d+", beside labels spelling a constant as Python's repr; it is the pattern's Python literal, a string matching '\\d+'. The depth bounds read at most 512 levels of nesting, got [[...]], which reads the value as a count; they are a value at most 512 levels deep and a value at most 128 recursive levels deep.
  • A record below the complement of two records is decided. {"t": int} against complement({"t": str} | {"t": bytes}) answered undecided, where a union of one record or of three decided: the set representation took the complement of the complement, and where a field spanned two kinds that rebuilt set cost more than a relation may spend. It meets the record with the union itself.
  • ==, hash, repr and a build refusal carry a fatal signal out. A constant whose __eq__, __hash__ or __repr__ raised KeyboardInterrupt read as unequal, as adding nothing to the hash and as <unrepresentable>. A length bound whose __index__ raised one was refused as no length, and a refusal naming an object whose __repr__ raised one named it <unrepresentable>. Each raises the signal; an ordinary exception reads as before.
  • The complement of an empty refinement is above every subject. complement(Annotated[str, Regex("x"), MaxLen(0)]) is the universe, since no string both matches x and has no characters, yet a union of forty pattern refinements answered undecided below it: the set representation read the pattern only by lowering the subject too, and that union is past what it lowers. The complement rule asks the refinement's own emptiness where disjointness declines.
  • Building the first validator does not hang beside an import on Python 3.15. There typing reaches annotationlib through a lazy import, and resolving one holds the interpreter's global import lock while it waits for the module. The first build read typing.ForwardRef that way, so a thread importing annotationlib at that moment -- dataclasses and inspect both do -- and the build waited on each other for good. The build imports annotationlib itself first, where the release has it.

0.0.14 - 2026-09-26

A typing and correctness release: five entries, two additions and three fixes.

A static checker reads a validator's set: Validator[T] is generic, a True from is_valid narrows to the type on a typed validator, and ensure and load return it. Two classes whose own __slots__ lay down layouts share no instance, so their meet is decided empty as a meet of two builtin subclasses is, and a slotted class over no builtin is below the complement of every builtin kind.

Three fixes. A protocol is a schema only where @runtime_checkable was applied to it, since a class that inherits the decorator answers isinstance with a warning from 3.15 and a refusal from 3.20, and under -W error was read as admitting nothing. The PyPy wheels are plain release builds: the profiled ones 0.0.12 and 0.0.13 carry die with a segmentation fault at the walk's depth bound. And there is a wheel for PyPy 8.0 beside the one for 7.3, since 8.0 changed the ABI tag and a wheel for one does not install on the other; the release runs the whole product suite on each PyPy wheel it ships.

Added

  • A static checker reads a validator's set. Validator[T] is generic in the type a checker reads for its schema: Validator(int) is a Validator[int], a dataclass or TypedDict class names its own type, a compiled validator keeps its own, and a native form, a Literal, an Annotated refinement or a combinator reads as Validator[object]. On a typed validator a True from is_valid narrows its argument to the type, and ensure and load return it; on an untyped one the answer stays a bool and ensure returns its argument's own type. The narrowing is a TypeGuard and not a TypeIs, because a False proves nothing a checker can use: this library's float refuses the int a checker admits there. A bare Validator annotation is Validator[Any] and takes every validator; the parameter is invariant, so a Validator[object] parameter takes only an untyped one. Validator[int] is a types.GenericAlias at runtime, and handed back as a schema it is refused by name. simplify is marked deprecated where a checker sees it, beside the warning it raises at runtime. ty, mypy and pyright read the stub alike.
  • Two classes laying down slots of their own share no instance. A class whose __slots__ add a slot lays down an instance layout, as a class built on a builtin does, and Python refuses a class deriving from two layouts unless one extends the other. intersection(C, D).is_empty() is True for two such classes neither of which derives from the other, Validator(C) is below complement(D), and a slotted class over no builtin is below the complement of every builtin kind. A plain subclass of a slotted class still meets a slotted subclass of the same base, in the class Python builds from both. An empty __slots__, or one naming only __dict__ and __weakref__, lays down nothing; the @disjoint_base decorator of PEP 800 is not read, since the runtime does not enforce it.

Fixed

  • The PyPy wheels no longer crash at the walk's depth bound. The released PyPy wheels were profile-guided builds like the CPython ones, and on a value nested to the depth bound a profiled extension ran out of the native stack budget PyPy's C-API layer sizes from the recursion limit before the walk reported recursion_limit; the process died with a segmentation fault. The PyPy wheels are plain release builds, which report the bound, and the release smoke runs the whole product suite on each PyPy wheel it ships rather than importing it alone.
  • A wheel for PyPy 8.0. PyPy 8.0 changed the ABI tag from pp73 to pp80, and an installer matches the tag exactly, so the pp73 wheels every earlier release built install on PyPy 7.3 and not on 8.0. The release builds a wheel for each on manylinux x86_64 and aarch64, and smokes each on the PyPy it is built for.
  • A protocol is a schema only where @runtime_checkable was applied to it. A subclass protocol inherits the attribute the decorator sets without the decorator, and was read as the isinstance check its base allows. Python 3.15 warns on every isinstance against such a class and 3.20 refuses it, and the walk reads a warning raised as an error as a non-member, so under -W error on 3.15 the schema admitted nothing and said nothing. It is refused on every release, naming the class and the decorator to add; decorated itself, the same class is read as before.

0.0.13 - 2026-09-24

A support and correctness release: ten entries, one addition and nine fixes.

Python 3.15 is supported, and every platform a wheel ships for but musllinux gets one for every interpreter the classifiers name: 0.0.12 left Apple silicon without 3.10 and every platform but Linux without free-threaded 3.14.

Two fixes are about a process rather than an answer. A recursive meet of records overflowed the native stack from is_empty() and is_subtype_of() and ended the interpreter, and two threads reaching a validator's first call together could stop each other on a free-threaded build.

The decision procedure decides more, and one wrong answer goes. A fixed-length sequence of unions against the union of its corners, a fixpoint's unfolding below the fixpoint, and a union of complements that covers every value are decided where they were undecided; a literal-keyed clause is read as the clause it is, where it refuted an inclusion no value refutes. On 3.15 a frozendict literal is refused as a frozenset literal is, rather than read as a constant.

Added

  • Python 3.15 is supported. The package names it in its classifiers, every push runs the suite on 3.15 as a merge gate, and a release ships cp315 and free-threaded cp315t wheels for manylinux, macOS and Windows x64, and cp315 for Windows arm64. Until 3.15.0 is published the wheels build against its release candidate, whose ABI the final release keeps. 3.10 stays the floor.

Fixed

  • Every platform gets a wheel for every interpreter the classifiers name. 0.0.12 shipped no cp310 wheel for Apple silicon and no free-threaded 3.14 wheel off Linux, though its classifiers name 3.10 and stable free threading: the macOS and Windows builds ran on the host and built for the interpreters the image carried. The release installs 3.10 through 3.14 and 3.14t there first, and Windows builds its free-threaded wheel in a job of its own. The smoke imports each wheel set on the floor, the newest release and the free-threaded build, and the free-threaded import must leave the GIL off. Windows arm64 keeps 3.12 and later, which its image carries.

  • Threads that reach a validator's first call together wait detached. The first call builds the validator's indexes, and a second thread arriving during the build waited attached to the interpreter. On a free-threaded build the builder interns strings, which can wait on a lock and let a stop-the-world pause begin that an attached waiter never reaches, and both threads stop. The waiter detaches, which is the wait PyO3 provides for this shape; the hang is reasoned from that contract rather than reproduced.

  • A recursive meet of records is decided rather than overflowing the stack. is_empty() and is_subtype_of(int) on Validator(recursive(lambda t: intersection({"a": union(t, int)}, {"a": union(t, str)}))) overflowed the native stack and ended the process; both answer. Emptiness of a meet of records asks the meet of the types a required key carries, and it read that meet with a fresh cycle check, so each unfolding of the fixpoint reached the same meet again. The meet is read under the cycle check of the node it belongs to, as a field of a single record is.

  • A fixed-length sequence of unions is decided against the union of its corners. Validator(tuple[K, K]).relation_to(union(*(tuple[a, b] for a, b in product(K, K)))) for K = int | str | bytes | float | None answered "undecided" and answers "subset", in a few milliseconds; with one corner left out it answered "undecided" and answers "not_subset". The product rule narrowed by every branch at every position and ran out of its work budget; it drops a branch that shares no value with what is left, which is exact, and it refutes where every union member it sets aside holds none of the subject's values. A widening: no answer that was a proof or a refutation changes.

  • A frozendict literal is refused rather than read as a constant. On Python 3.15, Validator(frozendict(a=int)) built Literal[frozendict({'a': <class 'int'>})], a schema admitting that one mapping and refusing frozendict(a=1) and {"a": 1}: a frozendict is not a dict, so it missed the dict literal's arm and fell to the constant reading. It raises NotImplementedError naming the dict literal and dict[K, V], as a frozenset literal does. frozendict[K, V] stays refused, and a frozendict value is admitted by collections.abc.Mapping and not by dict[K, V] or a record.

  • A relation between a builtin kind and a class with declared attributes is decided. The published decidability boundary listed an attribute record on either side as a conservative case, and int ≤ C and C ≤ int as "not proven" for a class with declared attributes. Both are refuted, with a value that decides each. A declared attribute is not a source of conservatism: the same relation declines for a class with no fields and decides for a class laid out as a kind, so the declines beside such a class are the open class order's, which the page assumes elsewhere. Thirty-two ordered pairs of schema nodes move from "not proven" to decided in the page's account. No answer the library gives changes; what changes is the account of it, and the ledger behind it, which drove a Protocol where it said it drove a record.

  • A fixpoint's unfolding is decided below the fixpoint however its body is spelled. Validator(union(m, list[t])).relation_to(t) for t = recursive(lambda x: union(m, list[x])) and m = intersection(int, union(float, bool)) answered "undecided" and answers "subset". A meet on the left of a reference was placed only where a member of the meet was below the reference, and where none was the pair ended undecided without the reference being unfolded; every other subject reached the unfolding. The meet rule runs first as before, and a meet it does not place is asked against the definition the reference names, as a union member always was. A widening: no answer that was a proof or a refutation changes.

  • A literal-keyed clause is a clause, and a relation reads it as one. Validator({"k?": str | int, str: int}).relation_to({Literal["k"]: str, str: int}) answered "not_subset" and answers "subset"; the two are one set, and is_equivalent says so. The walk reads a literal-keyed clause as the page states -- a key belongs when some clause admits it and its value, so {"k": 1} is a member through the str clause -- and the set representation read it as a field, which takes precedence, so it refuted an inclusion no value refutes. The lowering joins the clause's type with every clause that covers the key; a field of the same name is read instead of them, as before.

  • A union of complements whose inners share no value is the universe, and every subject is below it. Validator(complement(Annotated[int, pred])) .relation_to(union(complement(None), complement(set))), for a predicate pred, answered "undecided" and answers "subset": no value is both None and a set, so the union holds every value. The universe bound read a union's members by their regions and passed over the one the partition cannot read, which here is the member covering what the other leaves out. Where every rule declines, the union is now also read one De Morgan step in, as the meet of its members' complements, whose emptiness the rules decide. A widening: no answer that was a proof or a refutation changes.

0.0.12 - 2026-09-19

A correctness release: thirty entries, and twenty-nine of them are fixes.

The decision procedure decides more. A record whose fields each take several types is the union of the records that fix them; a subject sharing no value with any branch of a union is outside the union rather than undecided; a branch the subject cannot meet is dropped before the rest is asked; and divisibility between two moduli is settled by the steps themselves, which is the one addition.

The frontend refuses what it cannot build, rather than building a schema that denotes the wrong set. Four annotation forms, a frozen set literal, a character class carrying an operator the engine reads differently, an arity, and an order bound whose base and bound do not compare: each raised nothing and admitted the wrong values, and each is a refusal naming what it is about.

The walk says what it found. A union summary names its branches and keeps what stopped the walk, a report keeps the promises the error model makes, a refutation stands on a value, and a render that gave up says so.

Behind several of them is the descriptor's own reading of a kind: a string kind holds the characters no pattern matches, a set is at most as long as the values its element denotes, a dict has one entry for 1 and for True, and an integer bound at the end of the carrier keeps the integers past it. Each was a set the representation named wrongly, so each was a relation answered wrongly.

Added

  • Divisibility between two moduli is decided by the steps themselves. Validator(Annotated[int, MultipleOf(5000)]).is_subtype_of(Annotated[int, MultipleOf(2500)]) was False and is True. Every multiple of a is a multiple of b exactly when b divides a, so the two steps settle the inclusion between them and the size of either is beside the point; the question is %, asked of the steps, so a divisor of any numeric type answers by its own rules. The refutation and the meet still want the residue representation, and the decidability page says which is which.

Fixed

  • A subject outside every branch of a union is refuted, not left open. Validator({"a": chain, "b": int}).relation_to(union({"a": chain}, {"a": chain, "b": str})) answered "undecided" and answers "not_subset". A subject sharing no value with any branch is outside the union, so where it holds a value that value refutes the inclusion; reading the case as "proved, or not proven" kept the proof for an empty subject and dropped the refutation for every other.

  • A union branch sharing no value with the subject decides nothing. Validator(chain).relation_to(union(None, {"next": int})) answered "undecided" and answers "not_subset", naming the link the supertype refuses. A branch the subject cannot meet is dropped before the rest is asked, so an inclusion refuted by one branch is refuted rather than left open: the rules refute against a single supertype and have no arm that refutes against a union.

  • An order bound is refused where the base and the bound do not compare. Validator(Annotated[None, Ge(0)]), and the same over a dict or a set, built a schema that admitted no value at all and reported itself inhabited; each raises NotImplementedError naming the order the base cannot be asked. A bound is a question about two values, so the kind of the bound decides the answer with the kind of the base: Annotated[set[int], Ge(0)] is refused and Annotated[set[int], Ge({1})] admits the supersets of {1}. A list, a tuple and a set take a bound of their own kind, which they already ordered against.

  • A record is decided against the union of records it splits across. Validator({"a": int | str, "b": int | str}).is_subtype_of(...) over the four records that fix both keys was False and is True, and relation_to answers "subset" where it answered "undecided". The four records are that record, the way a fixed-length tuple is the union of the tuples it splits across.

    The same reading settles a difference written as one complemented union. a & ~(b | c) and a & ~b & ~c are one set, and both are decided where either is: a meet against a complemented union removes one part at a time rather than expanding the whole complement first, so the width the set representation's bound sees is the width of the answer rather than of the widest intermediate. The work one build may spend rises with it, to the figure a record of three fields against its eight corners costs.

    That difference is built under the allowance, which is what puts a ceiling on what asking costs: a record over sixteen corners spends the whole of it and answers "undecided", whichever way its fields and types divide them. An "undecided" is "not proven", never a claim that the relation fails.

  • A mapping opened frees the keys no clause claims. Validator(dict[str, int]).open().is_valid({1: "x"}) was False and is True. Openness is the default of the key-type region a schema's clauses leave over, so opening a mapping keeps what a str key maps to and frees every other key-type, and closing it refuses them again. A record is the case where the clauses claim nothing at all, which is why opening one frees every key -- that is the special case, not the rule.

    The same reading ends a clause being read two ways according to an unrelated field: Validator({"a": int, str: int}).close() dropped the str: int clause because a field was declared beside it, and keeps it now, as Validator({str: int}).close() always did.

    open on a mapping writes a clause keyed by a complement, which is a shape the set representation declines, so relations about such a schema fall back to the rules (docs/explanation/decidability.md records the decline). Membership is unaffected. Opening a record is unchanged in both answer and decidability.

  • A pattern prints the way Python spells it. The Regex marker inside a rendered schema carried the pattern in Rust's spelling: double quotes where Python's own repr picks single, and \u{7} for a control character, which is a truncated escape wherever Python reads it. A repr is an expression that rebuilds the schema, and the marker beside it has a repr of its own, so the two now agree character for character.

  • A render that gave up says so. A repr deeper than the renderer's own bound prints <...> where it stops. It printed ..., which is valid Python inside a subscript: eval on such a repr parsed it, built a validator, and handed back one that was not the schema printed -- a lossy rendering with nothing in it to say so. The mark is a syntax error wherever it lands, so a truncated render cannot be read back as a whole one. The bound is reachable: no single annotation can be written deep enough, but a chain of recursive definitions composes, and the documentation saying otherwise is corrected. tuple[T, ...] is unaffected -- that ellipsis is the annotation's own spelling.

  • A constraint is put to the kind a literal's constant belongs to. Annotated[int, MinLen(1)] is refused, because reading a length off an integer raises and the walk reads a raise as a non-member, so the schema would admit nothing and say nothing about why. Annotated[Literal[1], MinLen(1)] is the same schema one value narrower and compiled: it admitted no value and reported itself inhabited, a set that exists according to the library and holds nothing according to the walk. Every constraint family is affected -- a length or a pattern over a number, an order or a divisor over text -- and each is refused with the sentence its bare kind gets. A literal whose constant can be asked the constraint narrows exactly as its kind does, so Annotated[Literal["ab"], MinLen(1)] is unchanged.

  • A frozen set literal is refused, as its set sibling is. {int} is refused with a sentence naming set[T]; frozenset({int}) fell past every arm to the literal fallback and compiled to a schema admitting one frozen set holding the int type object, and no value a caller has. A frozenset is not a set, so the arm that refuses the one never saw the other. Both are now refused, each naming the parametrized form to write instead.

  • A NamedTuple prints as its name, as every other class does. repr(Validator(Point)) gave intersection(tuple[int, str], Point) where a dataclass gives DC and a plain class gives Plain, and docs/guides/schema-language.md states one rule for all of them. The schema is a meet either way -- an isinstance beside a deep check of what the class declares -- and the reading that names the class looked only for a record of named fields, which a NamedTuple does not have: its fields are positions. A union naming such a branch said the same thing twice over for the same reason, and now names the class.

  • An arity refusal names the annotation it is about. list[int, str], set[int, str] and frozenset[int, str] were refused with "expected exactly one type argument" -- a count, naming neither the annotation it was about nor what to write. A caller with one long annotation had nothing to search for. Each now names the spelling, says how many arguments were written, and says what to write instead, which differs by kind: a list of fixed length is the list literal [A, B], and a set schema is homogeneous, so several element types are their union set[A | B].

  • A walk reports what it found, at the edges a corpus reaches last. A dict holding a key whose __eq__ raises was reported as not being a dict, which sends a reader to the wrong value: it is a dict, it is not a member by the comparison-raises rule, and the field it cannot be shown to hold is reported missing. And MultipleOf over a step that is not a number is refused at build rather than compiled: the constraint is value % n == 0, a timedelta remainder equals no integer zero, and the validator that came out refused every value without saying why. int, float, Decimal and Fraction steps are unchanged.

  • A union summary names its branches, and keeps what stopped the walk. The summary names each branch "as each would name itself alone", and two branch kinds had no name of their own: a complement read as the word complement where alone it says not str, and a recursive branch as the word value where alone it names what it admits. Both name themselves. And a branch whose failure is recursion_limit, recursion_loop, mutated_during_validation or predicate_error keeps that report: each says the walk stopped rather than that the value is outside a set, each fails at the union's own location, and the summary counted that as no progress -- so a value nested past the walk's ceiling, or holding itself, came back as "matched no branch" with the reason dropped.

  • A report keeps the promises the error model makes. fail_fast=True stops at the first failure, and two sites reported two: a union aggregated the whole of its closest branch, and a mapping clause reported the key and the value together. Both report one, on the object path and the JSON path alike; the branch is still walked whole, because which branch is closest is measured by how far each descended. An undeclared integer key is named in the path as an integer, so err.path[-1] indexes back down to the entry -- one reading of a record gave the string of its digits and the other the integer, for the same value. A predicate's raised error is summarized like every other value a message carries rather than copied whole. An undeclared key's value reads as a Python repr, as every other value does. And a __repr__ raising a fatal signal while a message is built propagates it rather than folding it into <unrepresentable>, which is the rule at every other site a value answers a question.

  • An annotation builds the schema it names, or is refused. Four forms were read as a different schema, with no message saying so. typing.Tuple[()] is the empty tuple and built every tuple, admitting (1,), because a bare legacy alias and an empty parametrization are told apart by whether a type-argument list is present rather than by whether it is empty. A marker standing for the constraints it yields -- the grouping protocol annotated_types documents, which Interval and Len are written against -- was read by attribute alone, so a marker of your own left the schema admitting exactly what it excludes. {"a": int, "a?": str} names one field twice and built a record admitting nothing; it is refused. Literal[int] names no constant and built the int schema; it is refused. And a Regex marker carrying something that is not text names what it carries rather than reporting every one as bytes.

  • A string kind holds the characters no pattern matches. A str is a sequence of code points and a lone surrogate is one of them: "\ud800" is one character long and is a member of str. No codec encodes it, and a Regex matches the text of a string, so no pattern matches it -- which the walk has always said. The kind's universe stopped where the codecs do, so the difference between str and a catch-all pattern came out empty: Validator(str).relation_to(Annotated[str, Regex("(?s).*")]) answered "subset" against a string a caller can write in one line. It answers "not_subset", and the difference between the two reports the character that refutes it. A length bound counts that character as the one character it is, and inclusion between two patterns is unmoved.

  • A literal counts as one value only where its constant is one. Literal[c] denotes the values of c's type equal to c, which is one value where that type's equality is Python's own or compares by identity, more than one where __eq__ answers True for its siblings, and none where the constant does not equal itself. Counting every literal as one decided Annotated[set[Literal[E.A]], at.MinLen(2)] empty for an enumeration whose __eq__ lies, while {E.A, E.B} validates against it, and reported "not_subset" for Annotated[set[Literal[float("nan")]], at.MinLen(1)] against int, which asserts a value the schema has none of. The count asks the oracle, so an unreadable constant leaves the bound unread and the relation undecided. set[None], set[bool] and an ordinary enumeration are counted as before.

  • An integer bound at the end of the carrier keeps the integers past it. The integer component spells a set as intervals, and the bounds a schema names are 64-bit while Python's integers are not. Complementing a half-line that begins at the smallest such bound needs the integer just below it, which had nowhere to go, so the complement came out empty: Validator(int).relation_to( Annotated[int, at.Ge(-2**63)]) answered "subset" while -2**63 - 1 is an int that bound refuses, and intersection(int, complement(...)).is_empty() answered True over a difference holding that value. The answers are "not_subset" and False, and Le(2**63 - 1) answers the same way at the other end. A bound the carrier spells is decided as before, so Annotated[int, at.Ge(-2**63), at.Le(-2**63)] is proved below at.MultipleOf(2).

  • A container subclass does not talk its way into a schema. A schema over a container denotes the values it holds, and a subclass may override __len__ or __iter__ and answer anything. The override was believed, so Validator(set[int]).is_valid(s) was True for a set subclass whose __iter__ yields integers over storage holding "a", and Annotated[str, MinLen(3)] admitted a str subclass reporting nine over one character. Both answer False now, on is_valid and validate alike. Every container the walk reads answers this way: str, bytes, list, tuple, set, frozenset and dict are counted through their base type's __len__, and set and frozenset are walked through its __iter__. A subclass that overrides neither is read where it lies, so a NamedTuple and an ordinary container subclass pay nothing.

  • A set is at most as long as the values its element denotes. A sequence takes any length by repeating one element and a set does not: it holds each member once, so Annotated[set[None], MinLen(2)] denotes no set at all. The refinement was read as inhabited, and an inhabited subject is what lets a kind mismatch refute an inclusion -- so relation_to answered "not_subset" for Annotated[set[None], MinLen(2)] against None, asserting a value that does not exist, and is_empty answered False. Both answer for the set now: is_empty is True and the inclusion holds vacuously. set[bool] decides the same way at three members, set[int] at any bound, and a list is unchanged at every one.

  • A dict has one entry for 1 and for True. True hashes as 1 and equals it, so {1: "a", True: "b"} is a dict of one key -- while the descriptor held the two as separate slots and read a schema requiring both as inhabited. is_empty answered False for intersection(complement(Validator(dict[Literal[1], str])), complement(Validator(dict[Literal[True], str])), Validator(dict[Literal[1, True], str])), which admits no dict at all. The same shape over two integers is inhabited and still says so.

Literal[1] and Literal[True] stay disjoint: a key is an int or a bool and the walk tells them apart. What changes is that no dict carries both of them at once. - A character class carrying --, &&, ~~ or a nested [ is refused. Those combine classes in this engine and are literal characters to re, so one pattern denoted two sets and compiling it said nothing about which: Annotated[str, Regex(r"[\w--\d]")] admitted the non-digit word characters here and the word characters plus - there. re gives three different answers to the four forms -- it raises on the doubled hyphen, warns that it reserves the two symbol operators, and says nothing at all about a nested set -- so a reader porting a pattern found out at once, eventually, or never. Each now raises a ValueError naming the operator this engine would have read. Escape the characters to mean them literally, or write the classes out. A POSIX class ([[:alpha:]]) is read rather than refused: it is the divergence docs/guides/refinements.md already names, with both readings shown. - A pattern in extended mode may end in a comment. (?x) makes # run to the end of the line, and the anchor a whole-string match needs was appended after it -- so the closing half was swallowed and a pattern re accepts raised here. It is the form a long pattern is written in. - A relation answers for the set a schema denotes, at the edge of every kind. Eight readings named a set the schema does not have, and each is one wrong answer a caller could see. is_empty reported an inhabited schema empty and is_subtype_of reported an inclusion a value refutes, for: a length bound over a str or bytes, which counted every symbol but the newline; a str complement, whose universe was every byte string rather than the valid UTF-8 ones, so a difference holding only the rest read as inhabited; a set whose element kind is unhashable, whose members were cut although a subclass defining __hash__ is a legal member; an integer bound or step at the end of the 64-bit range, whose residue class was read as another; and a float bound written with an integer past 2^53, which no float equals and which was rounded to one that does. - A refutation stands on a value. relation_to answered "not_subset" -- which asserts a value of the subject lies outside the other schema -- where no such value exists: through a recursive reference the lowering had cut, for a dict[bool, V] against a clause listing both booleans, for a dict[int, V] against the bool keys it admits, for a clause whose key cannot spell a field name, for a union of literals whose only missing member is float("nan"), for a container of a meet of two unrelated classes, and for a class whose metaclass answers issubclass by running code or by raising. Each answers "undecided" or "subset" now, and is_subtype_of is unchanged on all of them. - is_valid and validate are one answer at the walk's depth bound. A homogeneous list, tuple or set of a scalar kind was admitted by the first and refused by the second at the deepest level a walk reaches. - A record resolves a key the way the dict does. A str subclass carrying a field's text was read as that field where a catch-all clause sat beside it, and as an undeclared key where none did, so one value had two answers. - A Regex marker is immutable. It is hashable and a schema holds it, so a pattern rebound after the fact changed the hash of a value already in use. - MultipleOf is a remainder equal to zero, which is what the constraint documents. The check read the remainder's truthiness, which differs for a type whose __bool__ and __eq__ disagree.

0.0.11 - 2026-09-15

A performance release. Nothing a caller writes changes: every entry below is the same answer arriving for less, or a platform the project states it supports and now proves. The frontend is the release's subject -- compiling an annotation got cheaper three separate ways, and the walk over a record got cheaper where a caller's dict already holds interned keys.

The one fix is PyPy's: a tuple subclass that overrides __len__ could send the walk past the end of its storage, which is a crash rather than a wrong answer, and it reached MinLen/MaxLen over such a subclass too.

Changed

  • Compiling a refinement is about three times cheaper. The frontend read a marker's optional attributes by trying them: a marker carries one of ge, gt, le, lt, min_length, max_length, multiple_of, pattern, flags and func and not the other nine, and each absence answered by raising an exception that was built, caught and dropped -- four hundred of them to compile fifty fields.

Two changes remove them. The absences that could be asked for are asked, through PyObject_GetOptionalAttr where the runtime has it, which is 3.13 onward. And which names a marker can carry is a property of its type -- every annotated_types marker is a slots dataclass, so Ge.ge is the descriptor that reads the slot and Ge.gt does not exist -- so the type is asked once and the answer kept, which removes the rest on every interpreter: below 3.13 there is no non-raising getattr, and func was asked with a bare one even above it. A marker that keeps its values in a dictionary of its own is read from that dictionary, which answers for a name it does not hold without raising; a type with a __getattr__ hook answers for names no dictionary holds, and is asked for everything exactly as before.

Fifty Annotated[int, Ge(0)] fields compile in 48 us where they took 153 on 3.14 and 45 where they took 144 on 3.12, and as a TypedDict in 100 where they took 240 and 86 where they took 238 (release build, idle machine, best of five runs of three hundred, twice).

  • A validator no longer imports dataclasses to ask whether a class is one. Every class node imported the module and called through it; the function is held after the first class that asks, and only after one asks -- importing dataclasses pulls inspect, copy and functools in with it, and the tracked objects they leave behind are walked by every later garbage collection, which costs a program that never compiles a dataclass 6.45% of its compile -- which is an instruction count, taken twice. A fifty-field dataclass compiles in 32.7--34.2 us against 34.4--35.8 (release build, idle machine, three runs each); a program that compiles none imports nothing.

  • Building a validator is about four times cheaper. The frontend asked the interpreter to import typing and resolve get_origin, get_args and the qualifier forms once per node of the annotation it was reading, for a module sys.modules has held since the first one. It holds them, as the cache beside them always said it did: a fifty-field record compiles in 222,939,220 instructions where it took 939,032,142.

  • Validating a record is cheaper when the dict's keys are interned, which is every dict written as a literal, every **kwargs and every __dict__. A validator's declared keys are interned too, so the probe compares pointers rather than bytes: a fifty-field record walk reads 29% cheaper with both sides interned, and about a percent cheaper with only ours.

  • PyPy 3.11 is a stated target. The Implementation :: PyPy classifier and docs/get-started/installation.md name the four wheels published for it from 0.0.10 onward -- manylinux and musllinux, x86_64 and aarch64 -- so a consumer there can tell a supported platform from an accident of the build matrix. Every push builds the extension against PyPy and imports it: the C API PyPy offers is not CPython's, and the difference shows at import rather than in any answer a validator gives.

Fixed

  • A tuple subclass that overrides __len__ no longer takes PyPy down. The tuple walk read its element count from PyTuple_Size, which is the storage on CPython and the object's own __len__ on PyPy's cpyext: a subclass reporting ten over one element made the walk read nine slots past the end of the allocation, and Validator(tuple[int, ...]).is_valid(...) segfaulted PyPy 3.11 rather than answering. A subclass is read through the base type's own slot, which means the same thing on every interpreter, and is walked over the elements it holds -- the answer CPython gave all along. An exact tuple is read where it lies, and so is a subclass that inherits tuple.__len__ rather than overriding it — every NamedTuple — which the first form of this repair copied along with the liars. Telling them apart costs one type lookup per validation: a three-field NamedTuple validates in 69 ns against 57 at 0.0.10, where copying it cost 100.

The same reading fixes MinLen/MaxLen over a list or tuple subclass on PyPy, which had believed the overridden __len__ while the shape beside it counted the storage.

0.0.10 - 2026-09-13

A second representation decides the three relations. Where the structural rules declined a pair, a set built per kind is asked instead, so is_subtype_of, is_equivalent and is_empty answer over a wider fragment without any of them answering differently: every relation this release adds moves a pair from not proven to decided, and a True still means what it meant. relation_to is the surface that tells those two apart, in three answers where the boolean has two.

typing.Any is the lattice top, a schema is built in the lattice normal form, and Validator.simplify is deprecated because the reduction it promised is the schema a caller already holds. Every compiled entry point takes its arguments positionally. This is a 0.0.x pre-release and those are breaking changes; each is written out below.

Added

  • Validator.relation_to(other) reports the inclusion in three answers where is_subtype_of reports two. A False from the latter folds together a value of this schema the other rejects and a question the procedure declines; "subset", "not_subset" and "undecided" keep them apart:
from valgebra import Validator

assert Validator(bool).relation_to(int) == "subset"
assert Validator(str).relation_to(int) == "not_subset"
assert Validator(bool).is_subtype_of(int) is True

"subset" is exactly what is_subtype_of answers True for, so no existing answer moves. A "not_subset" is a statement about a value: some member of this schema is outside the other, which the completeness probe holds by asking its universe for that value.

Which pairs earn one has grown since this entry was written, and keeps growing: a refinement against another of a different kind, two sequences whose elements share no value where a length bound rules the empty one out, a sequence against a bound it cannot meet, a class met with its attributes against a union or a recursive record, and a complement against a class. Each moves a pair from "undecided" to "not_subset", which is the direction the procedure may move in. docs/explanation/decidability.md is where that list lives rather than here; this entry is the answer, not its reach.

  • A NamedTuple denotes the tuple its fields lay out, so a relation between one and that tuple is decided rather than declined:
from typing import NamedTuple

from valgebra import Validator


class Pair(NamedTuple):
    x: int
    y: int


assert Validator(Pair).is_subtype_of(tuple[int, int])

A named tuple's positions are its attributes -- the class lays both down at once -- and the schema says so instead of describing the attributes alone, which denoted a wider set than the class has. A failing field reports its position rather than its name, because the shape carries positions; a passing instance is read once rather than twice, and checks about a third faster.

  • A union of literals is decided as the finite set it denotes, at any width and in both directions. A literal denotes one value, so a union of them denotes a set of values, and inclusion between two such sets is membership of every value of one in the other -- found is a proof, and one value found nowhere is a refutation naming what stands against the inclusion:
from typing import Literal

from valgebra import Validator

codes = Validator(Literal[tuple(range(10_000))])
shifted = Validator(Literal[tuple(range(1, 10_001))])

assert codes.relation_to(shifted) == "not_subset"

That pair read "undecided" at a thousand members, because the rules distributed one table against the other and spent the decision budget on the product. Membership is a walk of the two tables instead: ten thousand codes against ten thousand decide in about 9 ms, and the containment they do prove falls from 237 ms to 6 ms. Literal[float("nan")] is the empty set -- no value equals nan -- and the empty set is below every schema, which the core could not say before because a literal had no emptiness of its own. Two tables written in different orders are the same case: relating two validators renumbers one pool into the other, and a member set that is renumbered is put back in canonical order rather than left as the other validator happened to number it.

  • Relations over a bound on a float are decided. A bound was lowered into the descriptor only over whole numbers, so anything needing the descriptor and mentioning Annotated[float, Gt(0)] stayed undecided: float > 0 was not known to be below float, nor disjoint from int, nor from float < 0. A float bound is now a set of floats, with the side chosen by the base rather than by the operand's type — Gt(0) carries the integer zero and orders the floats all the same — and nan sits outside every interval, as Python's own comparisons put it. The completeness probe's random sweep reports fewer undecided relations in both directions, with none refuted by a value.

  • Schemas compare as sets. Each kind of value carries a representation closed under union, intersection and complement — integers as interval sets per residue class, floats as intervals over the ordered line with a bit for nan, strings and bytes as regular languages, sequences as automata over value sets, sets as powerset lines, dicts as map atoms with a default per key kind, classes as an order, objects as records over their attributes — so a <= b is asked as a & ~b admitting no value, which is what the relation means. Where the structural rules decline, that question is asked and answered:

from typing import Annotated, Literal

import annotated_types as at

from valgebra import Regex, Validator, complement, intersection

assert Validator(Annotated[str, Regex("a")]).is_subtype_of(Annotated[str, Regex("ab?")])
assert Validator(Annotated[int, at.MultipleOf(4)]).is_subtype_of(
    Annotated[int, at.MultipleOf(2)]
)
assert Validator(bool).is_subtype_of(Literal[True, False])
assert Validator(bool).is_subtype_of(Annotated[int, at.Ge(0)])
assert Validator(dict[Literal["a"], int]).is_subtype_of({"a?": int})
assert intersection(list[int], list[str]).is_subtype_of([])
assert Validator(tuple[int]).is_subtype_of(complement(tuple[str]))

Container meets, double complements, one regular language inside another, a kind against its own literals, one step dividing another, and the emptiness of a dict schema are decided this way. Twenty-five relations that answered False answer True, and the same shape written any other way is decided alike: a respelling such as union(A, complement(union(A, nothing))) is the universe.

Building a set representation costs about two orders of magnitude more than a rule that already answers, so it is asked only where the rules decline, and only for a schema it can build within a bound on the nodes it reads, the nesting it descends and the work it spends. Past any of those the answer is the conservative one, as before. What stays conservative is recursion, a length bound over a shape that is not text, an attribute record beside a builtin kind, and a predicate.

  • An integer key stays an integer in an error path. The path a failure reports is what a caller walks back down to the offending value, and every mapping key arrived as text -- so a dict keyed by numbers reported a location that indexed nothing, and d[2] and d["2"] were indistinguishable. A key that is a string or an integer is now itself; anything else has no spelling in a path made of those two and appears as its repr, as before.
from valgebra import ValidationError, Validator

raised = False
try:
    Validator(dict[int, int]).validate({1: 1, 2: "x"})
except ValidationError as error:
    raised = True
    assert error.errors[0]["path"] == (2,)
assert raised
  • A validator cannot be pickled, and says what to send instead. It holds the classes and callables its schema names, so the schema is what travels; rebuilding is about as cheap as unpickling would be. ValidationError pickles as before.

  • A length bound on a list or a tuple is decided. A length is a regular property of a sequence -- "any element, that many times" -- so the representation that holds sequences holds a bound on them, and a bound that used to be opaque to everything but a string is now part of the algebra.

from typing import Annotated

import annotated_types as at

from valgebra import Validator

assert Validator(Annotated[tuple[int, int], at.MinLen(3)]).is_empty()
assert Validator(Annotated[list[int], at.MinLen(3), at.MaxLen(2)]).is_empty()
assert Validator(Annotated[list[int], at.MaxLen(0)]).is_equivalent([])
assert Validator(Annotated[list[int], at.MinLen(2)]).is_equivalent([int, int, int, ...])

A set and a dict have a length their representations do not count, so a bound over one of those still stands.

  • A recursive schema is decided against the kinds its body admits. A reference is a cycle and a set representation has no room for one, so every relation over a fixpoint used to fall to the structural rules -- which read shapes, and cannot tell that a JSON value and a bytes share no value. The body is now unfolded once before the sets are built, with a bound standing where the reference was: the top where the schema is used positively, the bottom under a complement, which is what keeps a difference sound.
from valgebra import Validator, anything, complement, intersection, recursive, union

json = recursive(lambda j: union(None, bool, int, float, str, [j], {str: j}))
assert intersection(bytes, json).is_empty()
assert intersection(tuple, json).is_empty()
assert Validator(bytes).is_subtype_of(complement(json))
assert json.is_subtype_of(anything)
  • A recursive schema is one schema wherever it is combined. Merging a compiled validator used to copy its definitions, so two occurrences of one fixpoint became two definitions and every law that compares terms failed on it: intersection(json, complement(json)) was not empty and union(json, complement(json)) was not the top, for the same schema object on both sides. A merge now reuses definitions it already holds, and a fold that leaves one unreachable drops it -- so the top built that way is the top built any other way.
from valgebra import (
    Validator,
    anything,
    complement,
    intersection,
    nothing,
    recursive,
    union,
)

json = recursive(lambda j: union(None, bool, int, float, str, [j], {str: j}))
assert intersection(json, complement(json)) == Validator(nothing)
assert union(json, complement(json)) == Validator(anything)
  • Two spellings of one schema are one schema. A record's fields, a map's clauses, a refinement's markers and a union's members are sets, so the order they were written in is no longer part of the term: == says so, hash agrees, a union of two spellings folds to one member, and a validator is a usable dictionary key whatever order its schema was written in. A repeated marker is dropped, since a constraint written twice narrows once.
from typing import Annotated, Literal

import annotated_types as at

from valgebra import Validator, union

assert Validator({"a": int, "b": str}) == Validator({"b": str, "a": int})
assert Validator(Literal[1, 2]) == Validator(Literal[2, 1])
assert Validator(Annotated[int, at.Ge(0), at.Le(9)]) == Validator(
    Annotated[int, at.Le(9), at.Ge(0)]
)
assert union({"a": int}, {"a": int}) == Validator({"a": int})

repr prints the canonical order rather than the written one, which is the visible half: {"name": str, "age?": int} renders as {'age?': int, 'name': str}. It still rebuilds the schema. A test pinning the written order of a record's fields, a map's clauses or a refinement's markers needs updating; one pinning a union's or a literal's does not, since those keep the order they were built in.

  • A PEP 695 type alias that names itself builds the fixpoint it writes. The alias is the binder: it is reached again while its own body is read, and there is no lambda to carry the fixpoint, so the alias carries it. What it builds is what the explicit call builds, and mutual recursion is two aliases naming each other. An alias naming itself outside a structural constructor denotes no set and is refused when the validator is built, as an unguarded recursive already was. Before, such an alias was refused as a schema too deep to compile.
from valgebra import Validator, recursive, union

type Json = bool | int | float | str | list[Json] | dict[str, Json] | None

assert Validator(Json).is_equivalent(
    recursive(lambda j: union(None, bool, int, float, str, [j], {str: j}))
)
  • The three construction bounds are importable: MAX_SCHEMA_DEPTH, MAX_DEFINITIONS and MAX_SCHEMA_NODES are exported from valgebra and listed in __all__, so code sizing a schema against a bound reads the number rather than repeating it.

  • A class with declared attributes is the meet of its isinstance atom and a record of its attributes, and each half is a set the algebra relates on its own: an object schema is below its own class, an attribute record relates to another by width and depth whatever class it came from, and a record whose required attribute admits nothing is decided empty and one whose attributes are inhabited is decided inhabited — which the class half, being opaque, used to take away. The surface is unchanged: repr(Validator(Point)) is Point, a union names the class in its branch list, and a value of the wrong class reports one instance_type violation.

  • An intersection stops collecting violations once a member rejects the value itself rather than something inside it, the rule Annotated[...] already applied between a base and its constraints. A member that fails inside the value leaves the others meaningful and they are still collected.

  • Widening a literal union is decided by containment rather than by the product of the two member counts, so a table whose members are the same constants as the wider one's relates at any size. Constants pool by value, so two tables written independently share theirs and relate the same way.

  • ~~A is A, a union carrying a schema together with its complement is the top, and a meet of that pair is the bottom, all settled where the schema is built. The decision procedure has no rule for these shapes and does not meet one built through the constructors; a shape built another way — a recursive definition, a respelling, constants equal but not identical — reaches the procedure and is not decided. repr, ==, and the code a violation reports follow the canceled form: complement(complement(int)) reports int_type where it reported unexpected_match, and intersection(int, complement(int)) reports no_match naming nothing. A predicate and a class with an isinstance hook are exempt from the two canceling folds: the law is about sets, and an atom that answers by running code is not one.

  • A meet of two record schemas is decided empty when a key one side requires cannot hold — because the types the two give it share no value, or because the other side is closed and does not declare it. {"a": int} & {"a": str} is empty, and so {"a": int} is below ~{"a": str}. Only a required key empties a meet: two mappings, or two optional fields, always admit the empty dict.

  • A fixed-length sequence is decided against a union of fixed-length sequences it splits across, where no single branch contains it: tuple[int | str, int] is below tuple[int, int] | tuple[str, int]. The rule needs a fixed component count, so a homogeneous or variadic sequence is not decomposed, and branches of another container or arity drop out rather than blocking it.

  • A literal carries the kind of its constant, so it is decided against another kind: Literal["a"] is below ~int, and Literal["a"] & Literal["b"] is empty. Literal[1] and Literal[True] are disjoint although 1 == True, because a literal pins type(x) exactly. The rule applies to the builtin scalars, whose equality is Python's own; a meet of two Enum members stays conservative, since user-defined equality can admit one value for two constants.

  • A recursive schema is decided below its own body written out, and a refinement of a union below that union: recursive(lambda t: union(None, {"next": t})) is a subtype of union(None, {"next": <that schema>}), and Annotated[int | str, Ge(0)] of int | str. Trying a union's branches one by one commits to a branch, and a subject that lands in the union only once a reference is unfolded or a refinement drops to its base got no answer from it. Both rules are sound alone, so where both apply both are asked.

  • Every ValidationError carries the six attributes the error model documents, however it was made. The model describes failures and an error built by hand reports none, so it reads as empty — empty strings and empty tuples — rather than raising AttributeError for an attribute the type declares.

Changed

  • A length bound over a container that repeats one element decides whether the schema has a value, where it was left unknown. A value of any length is as many copies of one element, so the element decides it: a bound of zero is met by the empty container, a longer one by repeating an element. Three things follow. A recursive schema every unfolding of which needs one more element is reported empty, which the completeness ledger carried as a relation it could not decide. A refutation about such a schema is believed, so list[int] with a length bound is decided not below a tuple, by a rule rather than by the set representation. And the refuting half of the decision workload, whose hardest case was a fixed sequence with an unfillable position, falls by two orders of magnitude; the instruction gate holds the figure.

  • A relation between two classes is decided by a rule. A class whose metaclass leaves isinstance alone is read as holding an object -- the open world the set representation already works in, and the assumption every refutation this library makes about a class already rested on -- so the rules stop deferring to the sets for an answer the library had committed to: two unrelated classes read 1.2 us against 100, a dict subclass against a list 1.4 against 37, and a plain class against a dataclass 2.2 against 472. The answers are unchanged. A class whose metaclass answers with code of its own is read as before, which is not at all, and the decidability page states the assumption and where it is wrong.

  • A length bound over a string or a bytes decides whether the schema has a value, where it was left unknown. A string takes any length, so a bound its own lengths admit is met -- Annotated[str, MinLen(1)] is the non-empty string and it has one. Every refutation about such a schema is believed rather than left to the set representation: a non-empty string against another kind reads 0.9 us against 195, and against a mapping 0.9 against

  • A bound over a base whose values have no length still says nothing, and the reading declines.

  • A rule that answers for a shape and then declines hands the pair on, where it used to end the question. A refinement takes its base's supertypes and nothing else; a union supertype takes a subject that lands in one branch. A pair either leaves unproven now reaches the readings that decide what a pair with no rule is worth -- two sets that share no value, then the oracle, then the supertype's own shape. A bounded list against a mapping or a union of scalars reads 1.2 us against 395.

  • A subject outside a base is outside every refinement of that base. The value that refutes the one refutes the other, and it is the same value, so the refutation carries where the proof cannot: being inside the base says nothing about the constraints. A tuple against a length-bounded list reads 0.8 us against 460.

  • A class laid out as a builtin decides a relation by a rule. A class deriving from dict holds mappings and nothing else -- a subclass inherits the layout and cannot lay down a second -- so a list is not below it and the pair is refuted where it was left to the set representation: list[int] against such a class reads 1.2 us against 35. A class deriving from no builtin is not read this way and stays undecided, because a subclass of it may derive from one: an instance of a class built on that one and on str is a string and an instance of the first.

  • A pair whose kinds cannot overlap decides by a rule. Two distinct container kinds share no value, so every value of the subject is outside the supertype and the inclusion is refuted -- where the relation was left unproven and settled by lowering both sides into the set representation. list[int] against tuple[int, int] reads 0.6 us against 75 us, a mapping against a list 0.7 against 37, with the same answers.

  • A key one record requires and the other does not declare decides the pair by a rule. A clause governs the keys a value carries and requires none, so a record open to undeclared keys still holds a value without that key, and that value is one the supertype rejects. The relation was left to the set representation, which lowers both records to answer it -- and since a TypedDict is open by the typing spec, that was every relation between two of them: 1.0 us against 268 us for two eight-field TypedDicts, on the machine the performance page names.

  • A TypedDict value is read by its declared keys, as a closed record's is. A TypedDict is open -- the typing spec admits keys it does not declare -- and an open record was scanned key by key where a closed one was read by its keys, for a clause that admits any string. The keys settle it either way: every declared field is probed, and a key to spare is admitted when it is a string and refuses the record when it is not, which no key need be resolved to say. The same fifty-field value reads about a quarter faster as a TypedDict and its error report about a sixth, and neither answer moves.

  • Two schemas built alike share their nodes, so a question that reaches both is answered by identity rather than by walking two trees. A relation between a record schema and an equal one built separately reads 1.07M instructions against 4.97M under the core decision workload; the whole of that workload reads 21% down and the schema-transformation workload 4.5% down (scripts/perf_gate.py --decision --core). Building a validator pays 0.6% for the sharing, and the membership walk is unmoved. Nothing about what a schema denotes changes: the test that decides sharing is stricter than equality -- two spellings of the top stay two nodes, and repr gives back the one that was written.

  • Explaining a failure over a record costs a third less. The accepting walk scans a dict once and resolves each key it finds through a map built with the validator; the explaining walk asked the dict for each declared key by name, and a Rust string handed to a dict lookup is decoded into a fresh Python string and hashed before the probe can start -- once per field, per call. The declared keys are interned with the validator, as the attribute names already were, so the lookup is the probe alone. A fifty-field record reporting one bad field moves from 2.38 to 1.53 of pydantic-core's time, and the shape's ceiling comes down from 3.5 to 2.5. No answer changes.

  • The membership walk costs a third less. Every scalar arm of the walk ended in a helper that passed a boolean through and recorded a violation when it was false, and every element of a sequence went through a second helper between the loop and the walk. Both were out-of-line calls doing almost nothing: on a list of integers they were fifty of the hundred and fifty instructions spent per element. The two are inlined and the violation-recording half is marked cold, so the accepting path is a test where the answer already is. Measured on the fixed binding workload, 661.6M instructions against 968.9M, and against pydantic-core a 1,000-element array moves 0.88 to 0.57 of its time, a fifty-field record 0.58 to 0.49, and a JSON document 0.86 to 0.81. No answer changes.

  • Building and composing a schema costs less. A field name was owned outright by the field that declared it, so every pass that rebuilds a schema — opening or closing its records, reindexing it onto another validator's pools, simplifying it — copied the name of every field it carried across. On the core's fixed workload those copies were 38% of every heap allocation the crate made. A name is now shared: carrying it is a refcount bump and no allocation. The workload runs in 161.0M instructions against 233.5M, and compiling a fifty-field record costs 13.7 µs against 14.2. No answer changes.

  • A schema is built in the lattice normal form. The constructors folded two laws and left the rest standing, so union(int, int) rendered int | int and compared unequal to int while union(int, complement(int)) rendered anything — == was equality of nothing in particular, and repr showed a shape no rule was written for. Members of a join or a meet are flattened, ordered and deduplicated; the identities and the absorbing elements apply; ~anything is nothing and ~nothing is anything; and a join of one member is that member. So union(str, int) == union(int, str), intersection(int, anything) == Validator(int), and == is equality of a canonical form.

Three things a caller may see. repr shows the normal form, so a join renders its members in that order — a kind before a literal, for instance, while literals and classes keep the order they were written in, their pool slots being what orders them. A union's expected message lists its branches the same way. And Literal["x"], a join of one member, is that literal: it reports literal_error where it reported union_error.

Absorption is the one law left standing: A | (A & B) is A only when A contains A & B, and containment is the decision procedure — running it wherever a schema is built is the cost this design refuses everywhere else. is_equivalent decides it.

  • A bare container class is its kind. list and list[object] admit the same values — every list, a subclass instance included — and were different sorts of thing: a sequence node in one case, an isinstance atom in no kind at all in the other, so neither spelling was decided below the other and repr(Validator(list)) said list where the schema said otherwise. list, tuple, set, frozenset and dict name their kind's whole set, which is what the typing spec assigns an unparameterized generic and what the membership check always performed; the two spellings are one schema and compare equal. str, bytes, int and float always read this way. repr follows the schema, so Validator(list) renders list[anything].

A class built on a builtin narrows that kind rather than standing beside it, so it relates to it: Validator(MyInt) is below Validator(int) and Validator(MyStr) below Validator(str), and a meet of the two is empty. A class built on no builtin narrows nothing and relates to a kind in neither direction — class Both(Plain, MyStr) builds and its instances are strings, so a plain class's instances are not confined to any kind.

  • Every argument the compiled surface takes is positional. Validator, the combinators, and every method on a validator declare their parameters positional-only, matching the stub that already wrote them that way: a call naming one — v.is_valid(obj=x), Validator(schema=int), complement(schema=int) — raises TypeError. fail_fast is the one keyword the surface takes and it is keyword-only, as before. A stub that permits a keyword the extension refuses type-checks code that cannot run, and the two disagreed in nine places.

  • A TypedDict is open, which is the set the typing spec assigns it: a dict carrying keys the class does not name is admitted, and the keys it does name are checked and required exactly as before. closed=True and extra_items=T (PEP 728) are obeyed where the runtime provides them. The dict-literal form {"name": str} stays closed — it is this library's own spelling, and a schema written as a shape means that shape. Code relying on Validator(TD) to reject an extra key should write the TypedDict closed=True, or use the dict literal.

  • A map key schema narrowed by a constraint is refused where it is written. A clause's key says which keys it governs, and that must be a type — str, int, a union of them — or a Literal, which names the keys one by one. {Annotated[str, MinLen(2)]: int} and dict[Annotated[int, Ge(0)], str] now raise at construction. A narrowed key names part of a type, and two such clauses can overlap without either containing the other, which is a question this map model does not answer the same way twice. To constrain the keys themselves, check them beside the mapping rather than inside it. Keys that name a whole type are unaffected, dict[tuple[int, int], V] included.

  • typing.Any is the lattice top. It denotes what it always admitted — every value — and it is now the same schema as anything, so every law and every relation reaches it: Validator(Any) == Validator(anything), complement(Any).simplify() is nothing, intersection(Any, complement(Any)) is decided empty, and int is decided below Any. A gradual type is held apart from the top for a second question, consistency at the boundary between typed and untyped code, which a validator has no site for and never asked. What is kept is the spelling: repr(Validator(Any)) is still Any, and repr(Validator(anything)) is still anything. The spelling is not part of the set, so two schemas differing only in it are equal and nothing decides anything by it.

Code that read intersection(Any, complement(Any)).is_empty() as False, or Validator(Any).is_equivalent(anything) as False, now sees the opposite. Membership is unchanged: Any admitted every value before and admits every value now.

  • A constant is a value rather than an object. Two equal builtin scalars built separately — two "code_00042" strings read from different files — pool into one constant, where pooling by object identity made them two and left a schema mentioning both with two nodes no rule could see as one. The rule is a literal's own: same exact type, and equal. Literal[1] and Literal[True] stay two constants because the types differ; Literal[0.0] and Literal[-0.0] are one, because the values are equal and the sign of zero is not part of either; a nan and an integer too wide for the key pool by identity, since nan equals nothing at all and a wide integer has no key. Two independently written thousand-member tables relate at any size as a result.

  • repr renders an expression that rebuilds the schema. Three forms rendered something that either was not Python or was Python that builds a different schema: a recursive schema showed its back edge as ..., an open record showed its catch-all as ..., and both read back as Literal[Ellipsis], an ordinary dict key; the nullary product printed tuple[], which is not an expression. They render as recursive(lambda X: {'v': int, 'n?': X}), {'name': str, anything: anything} and tuple[()]. Two forms remain a rendering rather than a round trip, because neither is syntax: a class prints its name and a predicate prints Predicate(...).

  • A validator names the package it is imported from. Validator.__module__ is valgebra rather than the private extension underneath, which the API reference reserves the right to rename and tells callers not to import; the class is final, which it was already at runtime, and the annotation says so to a type checker.

  • A list or tuple counts one level of the construction depth bound, not two, so a schema can nest twice as deep before the bound refuses it: a chain of 128 nested lists now builds where 64 was the limit, and a chain that pins a length on each list reaches 64 where 43 was the limit. The sequence node carries its elements directly rather than as a regular expression over them, and the two levels a list spent were the expression's own constructors — levels a walk descended and a reader had no way to see. The bound itself is unchanged at 128 levels, and no schema that built before is refused now.

  • A schema refused for depth says so by name. The frontend's own descent limit stood at the same 128 levels as the construction bound, and once a list cost one level rather than two the two limits met: a too-deep chain of lists reported NotImplementedError about a type that never reaches a leaf instead of ValueError about the depth. The frontend now descends one level further than the deepest schema construction accepts, so the bound that tripped is the bound that speaks.

  • A union's expected names each branch the way that branch names itself when it fails alone, in place of the branch's node kind. A set of permitted strings — the commonest shape a field has — reported one of: literal, literal and now reports one of: the literal 'torch', the literal 'jax'; an Enum branch names its class. Literal[...] builds a union of its constants, so its constants are what the message lists. The list is bounded at the same number of branches the closest-branch search reads and ends in ... beyond it, so a wide union reports a readable prefix.

  • The completeness probe searches refinements. Its schema universe crossed every other kind the decision procedure treats differently and held no refinement, so that whole fragment was outside the reach of the gate docs/explanation/decidability.md cites as the reason an unlisted conservative answer cannot go unnoticed. Four atoms — two order bounds and two regexes — put it in reach, and the four suspected gaps they surface are on the ledger with the route to deciding each. No answer changed; nothing was found unsound.

Deprecated

  • Validator.simplify is deprecated and is removed in the next minor version. Calling it raises a DeprecationWarning. A schema is built in the lattice normal form, so the reduction it promises is the schema a caller already holds: repr shows it and == compares it. What it does beyond that is not a law but a decision — a meet of two provably disjoint kinds is the bottom, a join covering every region is the top — and is_empty, is_subtype_of and is_equivalent decide those and more without rewriting a term. Write intersection(int, str).is_empty() rather than repr(intersection(int, str).simplify()) == "nothing".

open, close and ensure stay. The first two rewrite every record a schema declares at any depth, inside its recursive definitions — a traversal that is not spellable one set at a time, which is what a whole-schema operation is.

Fixed

  • The extension imports on PyPy again. Telling a bare legacy alias (typing.List) from a parametrization with no arguments reached for types.GenericAlias through a binding whose type object is a CPython C-API static. That symbol is not part of the limited API and PyPy's cpyext does not export it, so the wheel built for PyPy failed to load — an undefined symbol at import, before any schema was built. The class is read from the types module instead, which is where every other special form this frontend recognizes is already read from, and which PyPy carries.

Only the PyPy wheels were affected; every CPython wheel imported and behaved the same throughout. A CI job now builds the extension for PyPy and imports it on every push, so the next such symbol fails there rather than in a release build.

  • A relation is refuted only where the subject of that comparison has a value, at every level of it. A container's rule carries its element's refutation up, and the reading that says whether a refutation is a claim was taken once, about the whole subject -- so a list of an element with no value, which is the empty list and below a list of anything, was reported outside it. The reading is taken where the refutation is made:
from typing import Annotated, Never

import annotated_types as at

from valgebra import Validator

no_value = Annotated[list[Never], at.MinLen(1)]
small = Validator({"f": no_value})
large = Validator({"f": no_value, "g": int})
assert Validator(list[small]).is_subtype_of(Validator(list[large]))

The same held for a set, a repeated tuple, a record whose field is optional, and any nesting of those. Shapes whose own form names a value -- a scalar, a container that admits an empty one, a union with such a member -- are read without a descent, which is what keeps the reading's cost where it was.

  • A sequence whose repeated element the rules cannot read is not refuted against a fixed length. tuple[X, ...] <= tuple[()] was refuted on the ground that a repeating tail cannot fit a fixed length, which stands only where X has a value: an X the rules cannot decide may admit none, and tuple[X, ...] is then the empty tuple, which fits. The refutation is believed where the element is proven inhabited and declined where it is not, and the descriptor -- which reads the element -- decides the pair:
from typing import Annotated, Never

import annotated_types as at

from valgebra import Validator

no_value = Annotated[list[Never], at.MinLen(1)]
assert Validator(tuple[no_value, ...]).is_equivalent(Validator(tuple[()]))

Found by the law that holds the two deciders to one answer: the rules refuted an inclusion the sets prove.

  • A schema disjoint from a meet is below that meet's complement. A <= ~B asks whether A and B share a value, and the meet it built for that question held B as a nested intersection where the rule that decides a meet empty compares the members of one intersection pairwise. Built through the meet constructor the members flatten, the pair meets, and the relation decides:
from valgebra import Validator, complement, intersection

small = Validator(int)
meet = intersection(Validator(str), Validator(bytes))
assert small.is_subtype_of(complement(meet))

The two deciders answered one question differently, which is what a disagreement between them looks like from outside: a relation that holds, reported as not proven.

  • Two wide literal unions are decided as sets. The core compares a union with a union member by member, so intersection(Literal[*range(20_000)], Literal[*range(20_000, 40_000)]).is_empty() made one call into the bindings per pair of members. The bindings answer the whole disjointness question in one pass where they can hash the constants, and decline — leaving the member walk — where they cannot.

  • A raised ValidationError builds its structured model when something asks for it. Every failure became a dict, a path tuple and six attribute writes at raise time, so a report over 10,000 failing rows cost 26 ms whether or not the caller read a row; it is now 9 ms for a caller that logs str(error), and still faster than before for one that reads errors. The attributes, their values and str() are unchanged, and pickling builds the model first so what crosses a process boundary is the same plain data.

  • import valgebra costs 0.9 ms, down from 32. __version__ was read with importlib.metadata.version(), which pulls email, zipfile, inspect and the compression modules to read a file that says what Cargo.toml already said — 20 of those 32 milliseconds, and a dozen modules dragged into any process that imports valgebra. The extension carries the crate's version instead; tests/test_version.py holds it to the installed distribution's.

  • A bound against nan is refused. Every comparison with nan is false, so Annotated[float, Ge(nan)] admitted no value at all — the empty set written as a bound, which no caller means and which neither decider proves empty. MultipleOf(nan) goes the same way. A bound that is empty because the order says so, such as Gt(inf), is kept: emptiness is then an answer.

  • A container is refused as a Literal argument, where it used to be read as a schema. The typing spec's Literal takes None, an enum member, or an int, bool, str or bytes value; Python does not reject the subscription, so Literal[[1]] reached the constant fallthrough and came out as list[Literal[1]], and Literal[{}] as the empty record — sets the caller did not ask for, with no message saying so. A float is still accepted: it is not a spelling the spec allows either, but it is a constant, which this library pools like any other. A bare ForwardRef is refused too, with the message a forward reference in a type argument already gave.

  • A bare legacy typing alias is the class it aliases. typing.Tuple was read as tuple[()] — the empty tuple, admitting () and nothing else — because a bare alias and a parametrization both carry no type arguments; typing.List, typing.Dict and typing.Set were refused for wanting one. Each is now its origin, so Validator(typing.Tuple) == Validator(tuple). tuple[()] keeps meaning the empty tuple, and a parametrized alias is unaffected.

  • NotRequired and Required are read under from __future__ import annotations. CPython computes a TypedDict's __required_keys__ when the class is created, from the annotations as written — under PEP 563 those are strings, so the qualifier was invisible to it and every optional key in every module using the future import compiled as required, failing correct data with missing_key. The resolved hint carries the qualifier and is now what answers, so a class means the same thing with the future import as without it.

  • Two spellings of one schema print the same way. A union's members are ordered by the IR's own order and a literal sorts there by its pool slot -- the order the constants were first seen -- so Literal[1, 2] and Literal[2, 1] were one schema by == and by hash and two by repr, against docs/guides/algebra.md's "repr shows it and == compares it". The literals in a union are now ordered by what they print; members that are not literals keep the place the normal form gives them.

  • Two validators that differ only in a constant no longer share a hash. __hash__ skipped every pool slot, so Literal[1] through Literal[1000] were one hash and a dictionary keyed by validators -- the reason the method exists -- degenerated into a linear scan, at 98 microseconds per lookup over ten thousand entries. The constant behind a slot is now folded in, which is 10,000 distinct hashes and 0.065 microseconds for the same registry. A constant with no hash contributes nothing, so a validator stays usable as a key whatever it pools.

  • An integer key of any size reaches an error path as an integer, and so does a bool. docs/guides/error-model.md promises a path a caller can walk back down to the value, and a key outside a machine word's range was rendered as its repr — '1180591620717411303424' — while True was excluded outright and arrived as 'True'. Both index nothing. d[True] and d[1] are one entry in Python, so a bool arrives as the integer it is.

  • Explaining a failure over a large value no longer costs the size of the value. Every violation summarized the value it was about by building that value's whole repr and keeping eighty characters of it, so a 20,000-deep list was rendered in full once per level of the walk: twelve seconds for a single error, against twenty microseconds for is_valid on the same value. A container is now rendered under a bound instead, which is 1.1 ms for the same case and flat in the depth. A value small enough to print is unchanged.

  • A class that holds its own validator is collected. A validator keeps the classes, enum members and callables its schema names, so Model.validator = Validator(Model) is a reference cycle -- and the type was not tracked by the cycle collector, so the collector never saw the edge from the validator back to the class and every such class leaked. A validator now traverses the objects it owns, and can be weakly referenced, so a registry keyed by schema can be a WeakValueDictionary and let its entries go.

  • A relation over a pattern whose determinization is exponential refuses instead of exhausting memory. Annotated[str, Regex("(a|b)*a(a|b){20}")] against Regex("(a|b)*") spent six seconds and 668 MB, and two more repetitions aborted the process on a four-gigabyte allocation: the automaton bound was checked after the regex engine had built the whole dense table. The engine now carries the size limit, so the family answers in under 100 ms at any repetition count. Membership is unaffected — the walk runs the pattern, not the automaton — and a pattern that stays small is still decided.

  • A Flag, an IntFlag and an Enum with no members are no longer read as the union of the members they list. A flag's | builds instances the class never listed, so Validator(Permission) was decided a subtype of Literal[Permission.READ, Permission.WRITE] although Permission.READ | Permission.WRITE is in the class and not in the literal; an enumeration with no members can still be subclassed, so Validator(Base) was decided a subtype of nothing although a subclass's member is an instance of it. Each is now the isinstance atom it was before the union reading existed, which leaves membership unchanged and the relations undecided.

  • A list that changes size while it is being checked is reported as mutated_during_validation, as a dict, a set and a record already were. A sequence is walked by position against a length read once, so a list grown by a predicate — or, on a free-threaded interpreter, by another thread — hid its new items from the walk, and one that shrank left the walk answering about items that were gone. In both directions is_valid returned True for a value that is not a member, and ensure handed that value back as checked. A tuple cannot be resized and keeps the plain iterator.

  • A dict schema is not decided below the complement of a record it shares values with. Negating "no key of this part, other than the ones this atom names, maps anywhere" tightened that part's default, and a default governs every key the atom does not name — the excluded ones included — so a record complemented twice came back forbidding the key it is about, and dict[str, int] was decided a subtype of ~{"a": int} although {"a": 1} is in both.

  • A numeric bound orders the booleans as well as the integers. bool is a kind of its own to the set representation and int denotes both, so a bound lowered as a set of integers alone denoted less than the schema does — and a smaller set has a larger complement, which is a subtype proof no value supports. A bound over a base that is not whole numbers, Annotated[float, Gt(0), Lt(1)] among them, is left to the structural rules rather than narrowed to integers.

  • Two plain classes are not decided disjoint. A class built on no builtin lays down no instance layout of its own, and reading two such classes as laying down different layouts made them share no value — though class Both(A, B) builds and its instances are in both. A layout conflict, which Python refuses to build a class across, still decides the pair.

  • open and close are functions on sets. {"a?": nothing} and {} admit exactly the empty dict — the field allows the key to be absent and admits no value for it, which is what a closed record already says of every key it does not name — yet .open() gave them different sets. The redundant field is now read away first, so equal records open to equal records. Two consequences a caller may see: Validator({}).open() now admits every dict, where it used to be left alone (having no field never made {} a mapping — a clause and no field does), and a record carrying a field its own clauses already cover loses that field when opened or closed.

  • A set reports its failing elements in an order the value fixes rather than the one the interpreter hands them over in, which moves with the hash seed. A set has no positions, so an element failure carries no index and only what it reports distinguishes it; the report is ordered by that, and fail_fast keeps the first of that order. The error model promised this determinism and a set was where it did not hold.

  • A dict key that is not a string appears in an error path as its full repr instead of a summary cut at forty characters, and a string key appears whole. A path is what a caller walks back down to the value, and a truncated key indexes nothing.

  • A refinement marker that would be dropped is refused instead. Four shapes silently produced a schema that admits either everything the marker excludes or nothing at all: a compiled re.Pattern's flags were discarded, so a case-insensitive pattern refused the strings it matches; a bytes pattern and a length bound no length can equal were skipped entirely, leaving the base unconstrained; and a marker from annotated_types that valgebra does not check, such as Timezone or Unit, was ignored as if it were someone else's metadata. re.IGNORECASE, re.MULTILINE, re.DOTALL and re.VERBOSE are written into the pattern; re.ASCII, re.LOCALE and re.DEBUG are refused by name. Metadata from outside that vocabulary is still ignored, as the typing spec asks.

  • A constraint no value of the base can answer is refused at build. Annotated[int, MinLen(1)] asked an integer for its length, which raises, and a raise reads as a non-member — so the schema denoted nothing at all while looking like a narrowing. A constraint some value of the base can answer is unaffected: a union with a text branch, or a class that may define what the constraint asks for, still narrows.

  • == on validators reads a pooled constant the way Literal does: same type and equal. Python's == runs across types, so comparing by equality alone made Validator(Literal[1]) and Validator(Literal[True]) the same validator while is_equivalent reported them disjoint — two answers about one pair. Comparing a validator with something else answers NotImplemented rather than False, so the other operand gets its turn as the data model asks; == still falls back to identity, so the answer a caller sees is unchanged.

  • A class is checked for the attributes it declares rather than for every annotation on it. A dataclass carrying an InitVar denoted the empty set — the marker names a constructor parameter no instance keeps, so every instance was refused for a missing attribute — and one carrying a ClassVar failed to build at all. Both are read as what they are, a field declared init=False is still checked because the instance carries it, and a TypedDict field qualified ReadOnly compiles to the type it qualifies instead of being refused.

  • A string in the argument of a typing form is refused instead of read as a literal. list["Account"] is a forward reference the typing spec resolves against the namespace the annotation was written in, and a runtime object carries no namespace; reading it as a constant built a list of the word, which refuses what the annotation admits. Validator still reads a bare constant as a literal wherever a value belongs — at the top level, in a native list or dict literal, and in Literal[...] — and still resolves a class's own string annotations.

  • An unpacked variadic tuple compiles to the shape it names. tuple[int, *tuple[str, ...]] is a fixed prefix followed by a repeating tail — the same shape tuple[int, str, ...] spells — and it was read as a two-element tuple whose second element is a tuple, so it refused (1, "a") and admitted (1, ("a",)). Unpack[...] says the same thing and compiles the same way; an unpacked fixed tuple splices its elements in. An element after the repeating tail names a set the sequence node cannot carry and is refused, as is unpacking a TypeVarTuple, which binds no element types at runtime.

  • The product-splitting rule builds its narrowed component through the schema constructors instead of writing at an index, so the double negation it used to manufacture — a complement of a branch component that is itself a complement — cancels where the rest of the tree says it does. The verdicts are unchanged; the rule stops producing a shape no other rule is written for.

  • A MultipleOf divisor of a different type than the value divides. The check reads the % operator rather than the value's __mod__ alone, and half of what % means lives on the divisor: a value that does not know it answers NotImplemented, the divisor's __rmod__ is asked next, and NotImplemented is truthy — so it read as a non-zero remainder. Annotated[int, MultipleOf(0.5)] refused every integer, and a Fraction or Decimal divisor refused every value.

  • A recursive definition nested inside another resolves its self-reference wherever the build put it. An inner fixpoint whose body names the outer variable compiles to a definition of its own, and the outer marker lands in that definition rather than in the outer body — so resolving the body alone left the marker dangling, and a dangling marker matches no value: the schema silently rejected members. Contractivity is checked over the whole system of definitions for the same reason, which refuses X = ~X and X = X | list[Y] written across a nesting; both built before and denoted no fixpoint.

  • A placeholder kept past the recursive builder it was handed to is refused at construction. The placeholder is an ordinary validator, so nothing stops a caller storing it, and what it stands for stops existing when the builder returns; using one afterwards built a validator that admitted no value and said nothing about why.

  • A container that changes size while it is being checked is reported as mutated_during_validation instead of aborting the interpreter. Membership runs Python at almost every entry of a dict or a set — a predicate, an __eq__, an isinstance hook — and a free-threaded interpreter lets another thread write to a shared value meanwhile; the iterators underneath both containers answer that with a panic, which crosses the boundary as a BaseException no caller catches as a validation failure. The walk reads both containers in a way that survives the change and reports a non-member, because a reading cut short decides nothing about the contents. Only a change in size costs the reading: a value rewritten in place is unaffected. The same code reports a value whose two readings disagree, which is the same failure of the check to have a stable value to decide about.

  • The membership walk counts the levels it holds open and refuses past 512 of them with recursion_limit, so a value inside every published construction bound cannot exhaust the native stack. Counting recursive unfoldings alone does not bound the frames: an unfolding descends the whole definition body, so a body at the schema-depth bound turns the 128 permitted unfoldings into thousands of frames. A recursive schema over a deep body meets the level bound and reports it; a linked list at the unfolding bound is unaffected, because the level ceiling sits above what that shape asks for.

  • ValidationError can be pickled, so a validation failure crosses a process boundary with its structured model intact. The exception's __module__ was a bare _valgebra, which names no importable module, and pickle locates a class by that string together with the qualified name — so a worker in a process pool or a task queue delivered a PicklingError naming an internal module instead of the validation result. The module is now valgebra, the package the name is exported from: it is baked into every serialized error, so it has to be the path that keeps resolving rather than the private extension underneath, whose name this reference reserves the right to change. A traceback and a repr read valgebra.ValidationError for the same reason.

0.0.9 - 2026-08-26

Two Annotated markers were read as something other than what they mean, and both produced a schema that denoted nothing or its complement. No other decision changes.

Fixed

  • A marker that is itself callable is asked, and only one that is not is taken apart by its .func. annotated_types.Predicate carries its callable there and is not callable, which is why the attribute is read at all — but Not and functools.partial carry one too.

Not(f) denotes the values where f is false, and it defines __call__ because calling is what applies the negation. Read by its .func it constrained by f instead, so every value under it got the opposite verdict: Annotated[int, Not(is_even)] admitted the even numbers.

partial(eq, 1) lost its bound argument the same way and became eq, which raises when called with a single value, so the schema admitted nothing at all.

Callability is the discriminator annotated_types itself encodes, so this is its rule rather than a heuristic.

  • A class in Annotated metadata is ignored, as the typing spec asks of metadata a consumer does not recognize. A marker carries its values on an instance and a class carries the descriptors that read them: Ge(0) holds ge = 0, while Ge holds the slot descriptor, and reading that as a bound built a comparison no value is ordered against. A class is also callable, and calling one constructs rather than asks — a unit marker written as a class answered no question and refused every value. Both traps ended in a schema denoting nothing.

Every other callable is still a predicate: a function, a lambda, a bound method, an object with __call__.

Changed

  • The documentation pages are numbered, so a page's URL carries its number: /03-schema-language/ where it was /schema-language/. The site's landing page is unchanged.

  • The published benchmark figures are re-measured, and the performance page now records the interpreter build its baseline was measured on rather than only the version: a free-threaded CPython runs this work about twice as slow as a GIL build of the same version. The ratios are unchanged — 7.6x on deep nesting, 2.0x on the wide record, 1.8x on the large array — and no decision or code path moved.

0.0.8 - 2026-08-25

Membership costs less on a refined schema, and no decision or message changes.

Changed

  • A violation's message is built when a violation is recorded rather than on every check. Naming a bound takes the bound's repr, and a value that belongs produces no violation to name it in, so accepting a value used to cost the size of the schema's operand rather than the size of the value.

Per-check cost over the bare type, release build, median of eleven runs of fifty thousand: a single comparison bound about 16 ns where it was about 123, and two about 29 where they were about 258. A comparison bound therefore costs less than a call into a Python predicate, which is the ordering the refinements page describes. The absolute figures are one machine's and move by around a tenth between runs; the ratio and the ordering are what travel.

The operand's size no longer enters into it. A passing check against Annotated[str, Ge(s)] measures about 51 ns for a one-character s and about 52 ns for a two-hundred-thousand-character one, against 143 ns and 303 us.

Every violation carries the message it carried, and every decision is unchanged.

  • The pages carry four things a reader could otherwise only find by experiment. The Regex dialect is the Rust engine's, not re's, and a pattern both engines accept can match different strings — POSIX bracket expressions, Unicode case folding of the Turkish dotless i, and \p{...} property escapes, so compiling successfully is not a test of which language a pattern is in. The depth budget accounts for refinements: a refinement is a node, so it costs a level on top of whatever it narrows, and the marker it carries makes no difference. A map can constrain some keys and leave the rest free by giving the permissive clause the complement of the claimed keys, where open admits a clause matching every key and so subsumes a narrower one. And the decidability boundary records that a meet of two distinct literals is not decided empty, with no sound rule to close it: a literal's equality is the value's own, so two literals can share a member while neither contains the other.

0.0.7 - 2026-08-25

Fixed

  • open, close, and simplify rewrite a validator's recursive definitions as well as its root. A recursive validator's root is a single back edge and every record, union, and refinement it declares lives in the definitions table, so all three were no-ops on exactly the schemas that carry the most structure: recursive(lambda n: {"a": int, "next": n}).open() admitted no undeclared key, and simplify left a recursive body unreduced.

  • The frontend descends as far as the construction bounds publish, so a schema those bounds accept is no longer rejected while being compiled. Sets, dicts, and records nest to the documented limit rather than to 100 levels, and the message a rejection carries reports how far the frontend descended rather than naming a cause it cannot know.

Added

  • is_empty decides an interval that skips every integer however the meet is spelled. intersection(Annotated[int, Gt(0)], Annotated[int, Lt(1)]) is empty, as Annotated[int, Gt(0), Lt(1)] already was: an intersection is a subset of each of its members, so a member bounded to the integers bounds the whole meet. A bool base counts integers for the same reason, since it subclasses int.

  • is_subtype_of decides attribute schemas across a class hierarchy. A dataclass or named tuple is below one over a base class whose every attribute it carries with a narrower schema, and below the bare class it is an instance of.

Both are conservative-to-decided moves: every relation that held in 0.0.6 still holds, and each carries the counter-direction that keeps it from over-firing.

Changed

  • open and close may raise ValueError. Opening a record adds a catch-all clause, so it grows the schema and the construction bounds apply to what it produces; a validator near the node limit can cross it.

  • A union of no members reprs as nothing and a meet of none as anything, because each constructor owns the identity of its own arity. repr(union()) was the empty string, which is not an expression that rebuilds the validator.

  • A widening between two eight-member literal unions costs 619 ns where it cost 1.66 us, and a union of opaque members decides up to about eight hundred members where it decided up to four hundred. The lattice bound asking whether a supertype covers the universe reads that supertype's region set instead of building the complement of a deep clone of it, and the emptiness folds stop once no later member can change the verdict.

  • Membership costs what it cost. The competitive baseline in the performance page is re-measured with its spread and the method that produced it: against pydantic in strict mode, 7.6x on a schema nested twenty-five deep, 2.1x on a fifty-field closed record, and 1.8x on a flat array of ten thousand integers.

On upgrade, handle ValueError from open and close where a schema is built in a loop, and expect a recursive validator to answer as the recursion says it should rather than as its root alone did. Nothing else changes.

0.0.6 - 2026-08-08

Changed

  • Internal only, with no change to what any schema admits or answers: the schema IR's purely structural walks share one declaration of each node's child schemas, and the two index remappings applied when validators compose — appending a constants pool, or interning one into another — share one walk over one set of payload sites. Every public method returns what it returned in 0.0.5, and validation, is_empty, the error model, repr, and every compiled form are unchanged.

Nothing to do on upgrade. The version exists so the reorganization ships under a release of its own rather than inside one whose entries describe something else.

0.0.5 - 2026-08-08

Added

  • tests/test_completeness_probe.py, which searches for relations answered False that no value in a wide universe refutes, and fails when one appears that is not written down with a reason. Every other instrument could only notice a completeness gap someone had already thought of; this one searches.

Fixed

  • is_subtype_of decides a closed record against a catch-all mapping: {"x": int} is recognized below dict[str, int]. The closed record had a dispatch branch of its own that read a field the supertype covers through a catch-all as undecided, though the general keyed-map rule beside it already decided exactly that. One rule serves every keyed-map shape.

  • is_subtype_of decides inclusion in a complement: A is below ~B when the two share no value, so list[int] is recognized below ~int and dict[str, int] below ~str. There was no rule for a complement on the right at all, so the relation was decided only when the left side was itself a complement.

Both change a public method's answer from False to True. No relation that answered True can answer False, and validation, is_empty, compilation and every rendered form are unchanged.

  • is_subtype_of and is_equivalent decide the lattice bounds by emptiness rather than by the shape of the atom. A schema that denotes the empty set without being spelled nothing — a record with an uninhabited required field, a canceling intersection — is recognized as a subtype of every schema, and one that covers the universe without being spelled anything is recognized as a supertype of every schema. Both previously answered False, which was sound but incomplete.

This changes the answer of a public method from False to True for those schemas. Nothing else moves: is_empty, validation, compilation and every rendered form are unchanged, and no relation that answered True can answer False. The gap was masked whenever the other side was scalar, because the region check decides that case correctly, so it was only visible against a container, a record, an instance or typing.Any.

0.0.4 - 2026-07-13

Added

  • The schema construction bounds are published as module constants — MAX_SCHEMA_DEPTH, MAX_DEFINITIONS, and MAX_SCHEMA_NODES — so a caller can size a schema against them.

Changed

  • Schema construction is bounded on every growth path, not only the combinator operators: the Validator constructor, the | operator, union, intersection, complement, recursive, and simplify all reject a schema past a fixed nesting depth, recursive-definition count, or total node count with a ValueError. simplify can therefore raise when negation-normal form expands a schema past the size bound (see docs/guides/limits.md).
  • The project describes its schema algebra as closed under its operations rather than complete.

Fixed

  • No sequence of public calls can overflow the native stack or exhaust memory while building a validator. A schema grown too deep through the Validator constructor or recursive, or too large by combining a validator with itself in a loop, is rejected at construction instead of crashing the interpreter on a later clone, drop, decision, or render. This extends the 0.0.3 composition bound, which rejected only the combinator operators and left the constructor and recursive paths unbounded.
  • Annotated[int, MultipleOf(0)] is rejected when the validator is compiled: no value is a multiple of zero, so the unsatisfiable schema raises a ValueError at construction instead of rejecting every value through a swallowed ZeroDivisionError at validation time.

0.0.3 - 2026-07-07

Added

  • Schema composition bounds nesting depth: combining validators with |, union, intersection, or complement past a fixed depth is rejected at construction with a ValueError, so a schema grown in an unbounded loop cannot overflow the native stack on its next check. A recursive back edge counts as a leaf, so a recursive schema's depth stays finite (see docs/guides/limits.md).
  • The type stub declares the __copy__ and __deepcopy__ methods a compiled validator exposes.

Fixed

  • Release builds report a well-formed validation error instead of panicking across the boundary when the error builder is handed no failures, and the per-element sequence walk folds an impossible missing-schema case to a non-member result rather than a panic.

0.0.2 - 2026-06-30

Added

  • valgebra.__version__ exposes the installed distribution version, read from the package metadata that maturin derives from the Cargo workspace manifest.

0.0.1 - 2026-06-29

The first published release. valgebra ships to PyPI as prebuilt wheels across the support matrix.

Added

  • Compile-once / validate-fast engine: Validator(schema) builds an immutable validator with validate (raises), is_valid (bool fast path), and ensure.
  • Typing-annotation frontend: scalars, None, Any, list/set/frozenset/ dict, fixed, variadic, and prefix-plus-tail tuples (tuple[A, B, ...]), unions and Optional, Literal, TypedDict, dataclasses, NamedTuple, enums, runtime-checkable protocols, NewType, PEP 695 aliases, and Annotated refinements (with bounds, length, and predicate constraints).
  • Native forms: a list literal as a sequence — [T], the fixed [A, B], and the prefix-plus-tail [A, B, ...] (a fixed prefix then a repeated tail); a dict literal as a closed record ("key?" optional); a single {KeyType: ValueType} entry as a mapping; and any constant as a typed literal.
  • A closed Boolean algebra: union, intersection, complement, anything, nothing, and a law-justified simplify, with the lattice laws property-tested. Conditional fields and key cardinality are composed from these (documented recipes), not shipped as combinators.
  • Set-relation queries on a compiled validator: is_subtype_of (set inclusion), is_equivalent (mutual inclusion), and is_empty (an unsatisfiable schema, including a recursive schema with no base case). Decided soundly across scalars, containers, records and mappings, sequence forms, class subtyping (issubclass), and literal values (by membership), and conservative on the cases it cannot prove.
  • Recursive schemas via the recursive fixpoint, with cycle and depth guards.
  • A structured, machine-readable error model: aggregated failures, opt-in fail-fast, and closest-branch reporting for unions.
  • JSON input on the Rust path: validate_json, is_valid_json, and load (validate and return the parsed value), consistent with the object path and faster than parse-then-validate.
  • A stable repr that renders a schema back to its annotation form.
  • Thread-safe, immutable validators.
  • A performance program: criterion and pytest-benchmark suites, a recorded baseline against pydantic-core and jsonschema, and a deterministic instruction-count CI regression gate.