xtr-serializer 6.0.0__py3-none-any.whl

xtr_serializer/.agents/skills/xtr-serializer/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: xtr-serializer
+description: How to write values as JSON and read them back exactly with xtr-serializer — a Serializer over normalizers and encoders, declared types, class hierarchies tagged on the wire, zone-aware datetimes, and refusals that never quote the input. Use when code must put a dataclass or model on a wire or in storage and get the same value back, when a subclass in a field typed with its base loses its fields, when a tuple, Decimal, UUID, bytes or datetime changes across a round trip, when a datetime must keep its zone name, when a class another library owns must be serializable, when writing a normalizer or an encoder of your own, when adding SerializerBundle or named serializers to an application on xtr-dependency-injection, or when reading debug:serializer.
+---
+
+# xtr-serializer
+
+A `Serializer` is a list of normalizers (object ⇄ plain data) and a list of encoders (plain data
+⇄ text). pydantic does the conversion. What this package adds is the chain, the context, the
+errors, the bundle — and one promise: a value is written, read back under the same options and
+compared, so what comes back equals what went in, or the write is **refused** with the path to
+the value that would have changed.
+
+Everything is judged against the **declared** type, not the runtime one.
+
+## Quick reference
+
+- Build one: `serializer = Serializer([PydanticNormalizer()], [JsonEncoder()])`. Priority is list
+  order; put a narrow normalizer before `PydanticNormalizer`, which handles nearly anything.
+- Write and read: `serializer.serialize(value, "json")` → `str`;
+  `serializer.deserialize(text, Order, "json")` → `Order`. `deserialize` takes `str` or `bytes`.
+- A bare `list`/`dict` declares nothing about its items: pass
+  `serialize(items, "json", type_=list[Order])` and `deserialize(text, list[Order], "json")`.
+  Without `type_`, a container is accepted only while everything in it is plain JSON already.
+- Steps on their own: `normalize`, `denormalize`, `encode`, `decode`.
+- Options go in a context mapping, built by `SerializerContextBuilder`,
+  `PydanticNormalizerContextBuilder`, `JsonEncoderContextBuilder`, or written by hand with the
+  public key constants (`STRICT`, `BY_ALIAS`, `ALLOW_EXTRA_ATTRIBUTES`, `JSON_INDENT`,
+  `COLLECT_DENORMALIZATION_ERRORS`, …) — [references/context.md](references/context.md).
+- Hierarchies: `@discriminator_map()` on the base, `@discriminator_name("delivery")` on each
+  class that is a value of its own. Wire key `"$type"` —
+  [references/hierarchies.md](references/hierarchies.md).
+- Zone-aware dates: annotate the field `ZonedDateTime`. A plain `datetime` field keeps the offset
+  only, and refuses a value in the hour the clocks repeat —
+  [references/datetimes.md](references/datetimes.md).
+- A class you do not own: `Annotated[T, PlainValidator(read), PlainSerializer(write, return_type=str)]`
+  — **validator first**; [references/foreign-types.md](references/foreign-types.md).
+- Your own normalizer or encoder:
+  [references/normalizers.md](references/normalizers.md).
+- In an application, with xtr-dependency-injection installed beside the package, activate
+  `SerializerBundle` and inject `SerializerInterface`. Only `xtr_serializer.bundle` needs the
+  container; `xtr_serializer.command` needs xtr-console.
+
+## Round-trip a value
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+from zoneinfo import ZoneInfo
+
+from xtr_serializer import JsonEncoder, PydanticNormalizer, Serializer
+
+
+@dataclass(frozen=True)
+class Order:
+    reference: str
+    total: Decimal
+    placed_at: datetime
+
+
+serializer = Serializer([PydanticNormalizer()], [JsonEncoder()])
+
+order = Order("A-17", Decimal("19.99"), datetime(2026, 3, 1, 9, 30, tzinfo=ZoneInfo("UTC")))
+text = serializer.serialize(order, "json")
+# '{"reference":"A-17","total":"19.99","placed_at":"2026-03-01T09:30:00Z"}'
+
+assert serializer.deserialize(text, Order, "json") == order
+```
+
+`Decimal`, `UUID`, `bytes` (base64url), `date`, `time`, `timedelta`, `Path`, enums, tuples, sets
+and frozensets all come back by their declared type. A naive datetime in a plain `datetime` field
+is refused — aware only.
+
+## Carry a class hierarchy
+
+```python
+from dataclasses import dataclass, field
+
+from xtr_serializer import discriminator_map, discriminator_name
+
+
+@discriminator_map()
+@dataclass(frozen=True)
+class Event:
+    name: str
+
+
+@discriminator_name("delivery")
+@dataclass(frozen=True)
+class Delivery(Event):
+    recipient: str
+
+
+@dataclass(frozen=True)
+class Mailbox:
+    latest: Event
+    history: list[Event] = field(default_factory=list[Event])
+
+
+mailbox = Mailbox(Delivery("sent", "ana@example.com"), [Delivery("sent", "bo@example.com")])
+
+back = serializer.deserialize(serializer.serialize(mailbox, "json"), Mailbox, "json")
+assert back == mailbox
+assert type(back.latest) is Delivery
+```
+
+`@discriminator_map` goes **after** `@dataclass`, and name every class before a type holding one
+is used. The rest — the wire key, intermediate bases, what a forged tag does, a model holding its
+own hierarchy — is in [references/hierarchies.md](references/hierarchies.md).
+
+## Testing
+
+- Use a real serializer; there is nothing to mock. `Serializer([PydanticNormalizer()],
+  [JsonEncoder()])` touches no I/O.
+- Assert the round trip, and the exact type of every nested value — equality alone would pass for
+  a subclass written as its base:
+
+  ```python
+  def test_a_delivery_in_an_event_field_comes_back_a_delivery() -> None:
+      serializer = Serializer([PydanticNormalizer()], [JsonEncoder()])
+      mailbox = Mailbox(Delivery("sent", "ana@example.com"))
+
+      back = serializer.deserialize(serializer.serialize(mailbox, "json"), Mailbox, "json")
+
+      assert back == mailbox
+      assert type(back.latest) is Delivery
+  ```
+
+- Assert refusals by type and path, never by the whole message:
+
+  ```python
+  import pytest
+  from xtr_serializer import NotNormalizableValueError
+
+
+  def test_a_forged_tag_is_refused() -> None:
+      with pytest.raises(NotNormalizableValueError) as raised:
+          serializer.deserialize('{"latest": {"$type": "nowhere"}}', Mailbox, "json")
+
+      assert raised.value.path == "latest"
+  ```
+
+- Name the hierarchy's classes at module level in the test module or a fixtures module, before
+  any type holding them is used. A name cannot be added once a schema covering the base is built,
+  and the registry lives for the process — so never register names inside a test body.
+- With a kernel, `assert_zero_config(SerializerBundle)` is the bundle's own contract test, and
+  `boot_for_test(kernel, overrides={SerializerInterface: ...})` swaps the serializer out.
+- Freeze a clock with `xtr-clock`'s `mock_time` when the value under test carries a date it
+  reads.
+
+## Use in an application
+
+`uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists
+`SerializerBundle`. There is no config file, environment or ignore line to write; the steps below
+that it cannot make, it prints.
+
+1. **Install** — `uv add xtr-serializer xtr-dependency-injection`: the bundle needs the container
+   installed beside it, never as an extra. Install xtr-console beside it for `debug:serializer`.
+2. **Activate** — `SerializerBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`,
+   imported from `xtr_serializer.bundle`.
+3. **Brings along** — the console bundle when xtr-console is installed. The logging bundle, and
+   the clock bundle under it, join only when xtr-logging is installed beside them too:
+   xtr-console does not depend on it.
+4. **Configure** — optional. With nothing configured there is one serializer writing JSON,
+   holding the pydantic normalizer, the JSON encoder and every normalizer and encoder **tagged**
+   for it — which a class subclassing one of the interfaces is, without being told, while a
+   service that only has their methods is not. A default context, named serializers and the tag
+   attributes are in [references/application.md](references/application.md).
+5. **Environment** — nothing is read from the environment. A value given as `env(...)` in a
+   configured default context must be set at boot, which builds every serializer.
+6. **Ignore** — nothing: the serializer writes no file into the project.
+7. **Use** — inject the interface; the default serializer has no qualifier, a named one is
+   reached by its name:
+
+   ```python
+   from typing import Annotated
+
+   from xtr_dependency_injection import Target, as_service
+   from xtr_serializer import SerializerInterface
+
+
+   @as_service
+   class Outbox:
+       def __init__(
+           self,
+           serializer: SerializerInterface,
+           api: Annotated[SerializerInterface, Target("api")],
+       ) -> None: ...
+   ```
+
+8. **Check** — `debug:bundles` shows `serializer` as `listed` and `active`.
+   `debug:serializer <module:Class>` shows the class's fields as it is read (`validation`) and as
+   it is written (`serialization`), and the classes of its hierarchy.
+9. **Remove** — drop the `BUNDLES` entry (`uv run xtr-recipes recipes:remove xtr-serializer`),
+   delete `<app>/config/packages/serializer.py` if you wrote one, then `uv remove xtr-serializer`.
+
+## Errors
+
+Every error derives from `SerializerError`. None repeats a value it was handed: a message says
+where the problem is and which types were involved.
+
+| Error | Raised when |
+| --- | --- |
+| `NotNormalizableValueError` | A value has no exact plain form, or data does not fit the declared type. `path`, `expected_types`, `current_type`, `error_type` |
+| `ExtraAttributesError` | Data carried fields its type does not declare, with `ALLOW_EXTRA_ATTRIBUTES` off. A `NotNormalizableValueError`, with `extra_attributes` |
+| `PartialDenormalizationError` | `COLLECT_DENORMALIZATION_ERRORS` is on and one or more values did not fit: `errors`, `data` |
+| `NotEncodableValueError` | Plain data has no form in the format, or the text is not valid in it |
+| `UnsupportedFormatError` | Nothing writes or reads the format asked for. A `NotEncodableValueError`, with `format` |
+| `CircularReferenceError` | A value contains itself. Also a `RuntimeError` |
+| `MappingError` | A hierarchy registered in a way that cannot work — duplicate name, class in no hierarchy, key a field also uses. A `LogicError`, raised at registration |
+| `LogicError` | The serializer was put together in a way no input could make right. Also a `RuntimeError` |
+| `InvalidArgumentError` | An argument or a configuration cannot be used. Also a `ValueError` |
+
+Raise these with their typed fields and **no `from` clause**: chaining an exception that carries
+the value puts that value in the traceback.
+
+## Do not
+
+- Do not expect a bare `list` or `dict` of objects to be written. Pass `type_=list[Order]`, or it
+  is refused.
+- Do not rely on a subclass surviving a field typed with its base without a hierarchy. Declare
+  `@discriminator_map()` and name the classes.
+- Do not register a `@discriminator_name` lazily — in a function, a test body, or after a type
+  holding the class has been used. It raises `MappingError`.
+- Do not use an import path, a class name or a module path as a wire tag. Only registered names
+  are read, and that is the point.
+- Do not put `PlainSerializer` before `PlainValidator` in an `Annotated`. The validator throws
+  the serializer away.
+- Do not store a `ZoneInfo` datetime in a plain `datetime` field and expect the zone back. Use
+  `ZonedDateTime`, or store UTC.
+- Do not pass a generator or a one-shot iterator as `normalizers` or `encoders`: the serializer
+  ends up empty.
+- Do not mutate the mapping a serializer was built with as its `default_context`, nor the context
+  a normalizer is handed — with no call context, every call gets the serializer's own.
+- Do not put a value in an error message, and do not `raise ... from` an exception holding the
+  input.
+- Do not expect a service that merely has a normalizer's methods to join a serializer: subclass
+  the interface, or tag it where you register it.
+- Do not register `Serializer` yourself in a container, or override a built-in normalizer or
+  encoder: the bundle's tag attributes are lost. Configure through `SerializerConfig` and the
+  tags.
+- Do not feed untrusted data of unbounded size to the decoder before capping the request:
+  crafted sets and integer-keyed dicts are quadratic.

xtr_serializer/.agents/skills/xtr-serializer/references/application.md

@@ -0,0 +1,89 @@
+# The bundle in an application
+
+With xtr-dependency-injection installed beside the package, list the bundle:
+
+```python
+# app/config/bundles.py
+from xtr_serializer.bundle import SerializerBundle
+
+BUNDLES = {SerializerBundle: {"all": True}}
+```
+
+Every serializer is registered under `SerializerInterface`, `NormalizerInterface`,
+`DenormalizerInterface`, `EncoderInterface` and `DecoderInterface` — the default one with no
+qualifier, a named one under its name.
+
+## Configure
+
+```python
+# app/config/packages/serializer.py
+from xtr_dependency_injection import configure
+from xtr_serializer import SKIP_NULL_VALUES, STRICT
+from xtr_serializer.bundle import NamedSerializerConfig, SerializerConfig
+
+
+@configure
+def serializer() -> SerializerConfig:
+    return SerializerConfig(
+        default_context={STRICT: True},
+        named_serializers={"api": NamedSerializerConfig(default_context={SKIP_NULL_VALUES: True})},
+    )
+```
+
+| `SerializerConfig` field | Meaning |
+|---|---|
+| `default_context` | Options every call to every serializer starts from; a call's context wins over them key by key |
+| `named_serializers` | Serializers besides the default one, each registered under its name as the qualifier. `"default"` and `"*"` are the names tags use, so neither names one here |
+
+| `NamedSerializerConfig` field | Meaning |
+|---|---|
+| `default_context` | Options every call to it starts from, over the bundle's own key by key |
+| `include_built_in_normalizers` | Whether the bundle's own pydantic normalizer joins it. `False` and the serializer has only what is tagged for it, and must be given one |
+| `include_built_in_encoders` | The same for the JSON encoder |
+
+## Tags
+
+A service joins a serializer by `NORMALIZER_TAG` (`"serializer.normalizer"`) or `ENCODER_TAG`
+(`"serializer.encoder"`), with three optional attributes:
+
+| Attribute | Means |
+|---|---|
+| `priority` | An `int`, higher tried first; without it, the definition's own priority, or 0 |
+| `serializer` | The name it joins, or a sequence of names: `"default"` (the default when absent), a configured name, or `"*"` for every serializer |
+| `built_in` | `True` for one a named serializer can leave out |
+
+```python
+from xtr_serializer.bundle import NORMALIZER_TAG
+
+
+def load_extension(self, config, services, builder) -> None:
+    _ = services.set(MoneyNormalizer).add_tag(NORMALIZER_TAG, priority=10, serializer="*")
+```
+
+- A class **subclassing** one of the interfaces carries the tag without being told, with no
+  attribute — which puts it in the default serializer at its definition's own priority. A class
+  that only has a normalizer's or an encoder's methods carries nothing: tag it where you register
+  it. A serializer holds exactly what is tagged for it.
+- Such a class is tagged before its own `@autoconfigure_tag(...)` is read, so those attributes are
+  dropped. Tag it where you register it, or use `@as_tagged_item(priority=...)`.
+- **Checked at build**: a tag that cannot be read, one naming a serializer that does not exist,
+  and a serializer left without a normalizer or an encoder all fail the build. Booting then builds
+  every serializer, so a service tagged as what it is not fails there rather than on the first
+  call.
+- **Named copies**: each named serializer gets its own instance of every service it shares with
+  another, under the key `serializer.<name>[.<qualifier>]` — a service is handed the serializer
+  holding it, and one instance can only be handed one. A decorator wraps the default serializer's
+  instance only.
+- Strings in a configured default context go through `%parameter%` resolution twice, so a literal
+  `%` is written `%%%%`, and `'%%kernel.environment%%'` arrives as `'dev'`. A string such as
+  `'10%%-20%%'` fails the boot with `ParameterNotFoundError` for the parameter `-20`.
+- **Zero config**: one serializer writing JSON. Nothing is converted until something asks for one.
+
+## debug:serializer
+
+In debug mode, with a console bundle active, `debug:serializer <module:Class>` shows the fields of
+a class as it is read (`validation`) and as it is written (`serialization`), and the classes of its
+hierarchy. It takes a class: a parametrized generic alias (`Box[int]`, `list[int]`) and a TypeVar
+are refused, while pydantic generic models (`Page[int]`) work. Running it on a class of a hierarchy
+locks that hierarchy for the process. Its tables are pydantic's JSON schema, with that schema's
+blind spots, and assume the default options rather than a configured default context.

xtr_serializer/.agents/skills/xtr-serializer/references/context.md

@@ -0,0 +1,59 @@
+# Options: the context
+
+Every call takes a context — a plain mapping each step reads its own keys from. A builder per
+step sets them with typed methods, and each leaves the other steps' keys alone, so they chain by
+handing one's `to_dict()` to the next.
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+from zoneinfo import ZoneInfo
+
+from xtr_serializer import (
+    JsonEncoder,
+    JsonEncoderContextBuilder,
+    PydanticNormalizer,
+    PydanticNormalizerContextBuilder,
+    Serializer,
+)
+
+
+@dataclass(frozen=True)
+class Order:
+    reference: str
+    total: Decimal
+    placed_at: datetime
+
+
+serializer = Serializer([PydanticNormalizer()], [JsonEncoder()])
+order = Order("A-17", Decimal("19.99"), datetime(2026, 3, 1, 9, 30, tzinfo=ZoneInfo("UTC")))
+
+context = (
+    PydanticNormalizerContextBuilder(JsonEncoderContextBuilder().with_indent(2).to_dict())
+    .with_ignored_attributes({"total"})
+    .to_dict()
+)
+# {'json_indent': 2, 'ignored_attributes': frozenset({'total'})}
+
+serializer.serialize(order, "json", context)
+# '{\n  "reference": "A-17",\n  "placed_at": "2026-03-01T09:30:00Z"\n}'
+```
+
+| Builder | Sets |
+|---|---|
+| `SerializerContextBuilder` | `with_collect_denormalization_errors` |
+| `PydanticNormalizerContextBuilder` | `with_attributes`, `with_ignored_attributes`, `with_skip_null_values`, `with_skip_unset_values`, `with_skip_default_values`, `with_by_alias`, `with_strict`, `with_allow_extra_attributes`, `with_from_attributes`, `with_populate_by_name` |
+| `JsonEncoderContextBuilder` | `with_indent` |
+
+- Builders are immutable: each `with_*` returns a new one, so a builder holding an application's
+  defaults can be extended for a single call.
+- Each key is a public constant with the same name in upper case — `STRICT`, `BY_ALIAS`,
+  `JSON_INDENT`, `COLLECT_DENORMALIZATION_ERRORS` — for a context written by hand.
+- A serializer built with `default_context=` starts every call from those options, and a call's
+  context wins over them key by key. With no call context, every call is handed the serializer's
+  own mapping: copy it before changing it.
+- The whole context also reaches pydantic as `info.context`, so an application's validators read
+  it.
+- Leaving fields out (`with_attributes`, `with_ignored_attributes`, the `skip_*` options) is a
+  partial write: it is checked, but not read back, so the exactness promise does not apply to it.

xtr_serializer/.agents/skills/xtr-serializer/references/datetimes.md

@@ -0,0 +1,41 @@
+# Dates that keep their zone
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+from xtr_serializer import JsonEncoder, PydanticNormalizer, Serializer, ZonedDateTime
+
+serializer = Serializer([PydanticNormalizer()], [JsonEncoder()])
+
+
+@dataclass(frozen=True)
+class Reminder:
+    at: ZonedDateTime
+
+
+repeated = datetime(2026, 10, 25, 3, 30, tzinfo=ZoneInfo("Europe/Bucharest"), fold=1)
+
+text = serializer.serialize(Reminder(repeated), "json")
+# '{"at":"2026-10-25T03:30:00+02:00[Europe/Bucharest]"}'
+
+read = serializer.deserialize(text, Reminder, "json")
+assert read.at == repeated
+assert (read.at.tzinfo, read.at.fold) == (ZoneInfo("Europe/Bucharest"), 1)
+```
+
+One string, the form RFC 9557 gives: the ISO datetime with its offset, then the zone's name.
+
+- The same value in a plain `datetime` field is refused when it is written, naming the field: in
+  the hour the clocks repeat the offset alone cannot tell the two 03:30s apart.
+- `ZonedDateTime` refuses a naive datetime, a fixed offset and a zone with no name; reading
+  refuses text not in that form, an unknown zone, and an offset the zone does not have at that
+  time. Each unknown zone name is looked up on disk.
+- A plain aware `datetime` reads back with pydantic's own `TzInfo`: equal, not the same tzinfo
+  object or class.
+- `date`, `time`, `timedelta`, `Decimal`, `UUID`, `bytes` (base64url), `Path`, enums, tuples,
+  frozensets and sets all round-trip by their declared type, with no annotation.
+- More than six fractional-second digits in a datetime are truncated.
+- With pydantic before 2.14, a `NamedTuple`'s items are written by their runtime type, so a
+  `ZonedDateTime` inside one is refused.

xtr_serializer/.agents/skills/xtr-serializer/references/foreign-types.md

@@ -0,0 +1,66 @@
+# Serialize a class you do not own
+
+A class another library owns, which must stay free of the conversion engine, is made serializable
+on the field rather than on the class, with pydantic's own annotations.
+
+```python
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Annotated, TypeAlias
+
+from pydantic import PlainSerializer, PlainValidator
+
+from xtr_serializer import JsonEncoder, PydanticNormalizer, Serializer
+
+serializer = Serializer([PydanticNormalizer()], [JsonEncoder()])
+
+
+class Money:
+    """An amount in a currency, owned elsewhere and knowing nothing of this package."""
+
+    def __init__(self, amount: Decimal, currency: str) -> None:
+        self.amount = amount
+        self.currency = currency
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Money):
+            return NotImplemented
+        return (self.amount, self.currency) == (other.amount, other.currency)
+
+
+def _write_money(money: Money) -> str:
+    return f"{money.amount} {money.currency}"
+
+
+def _read_money(value: object) -> Money:
+    if not isinstance(value, str):
+        raise ValueError("money is written as text")
+    amount, _, currency = value.partition(" ")
+    if len(currency) != 3 or not currency.isalpha():
+        raise ValueError("money is an amount, a space and a three-letter currency")
+    return Money(Decimal(amount), currency)
+
+
+Priced: TypeAlias = Annotated[
+    Money, PlainValidator(_read_money), PlainSerializer(_write_money, return_type=str)
+]
+
+
+@dataclass(frozen=True)
+class Invoice:
+    total: Priced
+
+
+text = serializer.serialize(Invoice(Money(Decimal("12.50"), "EUR")), "json")
+# '{"total":"12.50 EUR"}'
+
+assert serializer.deserialize(text, Invoice, "json") == Invoice(Money(Decimal("12.50"), "EUR"))
+```
+
+- **List `PlainValidator` before `PlainSerializer`.** The validator replaces the whole schema the
+  annotations before it built, the serializer among them; put it first and the `PlainSerializer`
+  after it is kept.
+- The reader raises a plain `ValueError` with words that do not quote the value, and it comes back
+  as a refusal carrying the field's path.
+- The annotation lives on the field, so the class itself stays free of the conversion engine — and
+  this works inside a hierarchy's values too.

xtr_serializer/.agents/skills/xtr-serializer/references/hierarchies.md

@@ -0,0 +1,77 @@
+# Class hierarchies
+
+A field typed with a base class holds a value of any subclass. Declare the hierarchy once on the
+base, and name each class that is a value of its own.
+
+```python
+from dataclasses import dataclass, field
+
+from xtr_serializer import (
+    JsonEncoder,
+    NotNormalizableValueError,
+    PydanticNormalizer,
+    Serializer,
+    discriminator_map,
+    discriminator_name,
+)
+
+serializer = Serializer([PydanticNormalizer()], [JsonEncoder()])
+
+
+@discriminator_map()
+@dataclass(frozen=True)
+class Event:
+    name: str
+
+
+@discriminator_name("delivery")
+@dataclass(frozen=True)
+class Delivery(Event):
+    recipient: str
+
+
+@dataclass(frozen=True)
+class Mailbox:
+    latest: Event
+    history: list[Event] = field(default_factory=list[Event])
+
+
+mailbox = Mailbox(Delivery("sent", "ana@example.com"), [Delivery("sent", "bo@example.com")])
+
+text = serializer.serialize(mailbox, "json")
+# '{"latest":{"$type":"delivery","name":"sent","recipient":"ana@example.com"},
+#   "history":[{"$type":"delivery","name":"sent","recipient":"bo@example.com"}]}'
+
+back = serializer.deserialize(text, Mailbox, "json")
+assert back == mailbox
+assert type(back.latest) is Delivery
+```
+
+A forged, unknown or missing tag is refused:
+
+```python
+try:
+    serializer.deserialize('{"latest": {"$type": "nowhere", "name": "sent"}}', Mailbox, "json")
+except NotNormalizableValueError as refusal:
+    print(refusal)
+    # at 'latest': the data must be an object whose '$type' names a class the declared type
+    # takes (got 'dict')
+```
+
+- The wire key is `"$type"` by default — no name a field can have. `@discriminator_map("kind")`
+  picks another, which must be no field's name or alias.
+- A name is the data's word for the class: choose one that stays when the class moves or is
+  renamed. Only a named class is written; a value of an unnamed subclass is refused rather than
+  written as its base, so name even a subclass that adds no field.
+- A tag is resolved among the registered subclasses **of the declared type only**, so data cannot
+  name a class of another hierarchy or one the field does not take.
+- Dataclasses, pydantic dataclasses and models all work, as do intermediate bases: a field typed
+  with one takes the named classes under it. A generic class cannot be in a hierarchy.
+- Apply `@discriminator_map` after `@dataclass`, and before `@discriminator_name` when the base
+  has a name of its own.
+- Name every class of a hierarchy before a type holding one is used — and before a model holding
+  one is defined, as a model builds its schema then. Naming one later raises `MappingError`, and
+  hierarchy classes live for the whole process. A model holding its own hierarchy needs
+  `model_config = ConfigDict(defer_build=True)`.
+- Reading a nested hierarchy value costs depth × size; the decoder caps nesting at about 198
+  levels.

xtr_serializer/.agents/skills/xtr-serializer/references/normalizers.md

@@ -0,0 +1,79 @@
+# Normalizers and encoders of your own
+
+A normalizer handles the types it reports and leaves the rest; the serializer gives each value to
+the first one that handles it, in the order the list has them. Put yours before the pydantic
+normalizer, which handles nearly anything.
+
+```python
+from dataclasses import dataclass
+
+from xtr_serializer import (
+    JsonEncoder,
+    NotNormalizableValueError,
+    PydanticNormalizer,
+    Serializer,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Point:
+    x: int
+    y: int
+
+
+class PointNormalizer:
+    """Writes a point as a pair of numbers, and reads that pair back into a point."""
+
+    def normalize(self, data, format=None, context=None, *, type_=None):
+        if not isinstance(data, Point):
+            raise NotNormalizableValueError("only a point is written here")
+        return [data.x, data.y]
+
+    def supports_normalization(self, data, format=None, context=None, *, type_=None):
+        return isinstance(data, Point)
+
+    def denormalize(self, data, type_, format=None, context=None):
+        match data:
+            case [int() as x, int() as y] if type_ is Point:
+                return Point(x, y)
+            case _:
+                raise NotNormalizableValueError(
+                    "a point is a pair of whole numbers",
+                    expected_types=("Point",),
+                    current_type=type(data).__name__,
+                )
+
+    def supports_denormalization(self, data, type_, format=None, context=None):
+        return type_ is Point
+
+    def get_supported_types(self, format):
+        return {Point: True}
+
+
+serializer = Serializer([PointNormalizer(), PydanticNormalizer()], [JsonEncoder()])
+assert serializer.serialize(Point(3, 4), "json") == "[3,4]"
+assert serializer.deserialize("[3,4]", Point, "json") == Point(3, 4)
+```
+
+- Implement `NormalizerInterface`, `DenormalizerInterface` or both; an encoder implements
+  `EncoderInterface`, `DecoderInterface` or both, as `encode`, `supports_encoding`, `decode`,
+  `supports_decoding` and a format string of its own. They are `Protocol`s — subclassing is
+  optional in code, the methods are what counts, and `normalize` / `supports_normalization` must
+  accept the keyword-only `type_`.
+- `get_supported_types(format)` is how a serializer skips you without asking: a key is a class
+  (standing for its subclasses), `"object"` (every class) or `"*"` (anything at all, type
+  expressions such as `int | None` included). Its value is `True` when the answer rests on the
+  type and the format alone — asked once per type and remembered — `False` when it rests on the
+  value or the context too, and `None` for a type you do not handle.
+- A key naming the type itself counts first, so `None` there settles it; failing that, the first
+  class key covering the type, in the order reported, counts — so list narrower keys first. A
+  class key never covers `list[Point]` or `Point | None`; only `"*"` does.
+- **Priority is list order**, both in code and, through the bundle, by the tag's `priority`
+  attribute, highest first.
+- Take `SerializerAwareInterface`, `NormalizerAwareInterface` or `DenormalizerAwareInterface` and
+  the serializer hands itself over, for values nested inside yours.
+- `Serializer` does not look inside a bare list or dict: it goes to a normalizer whole, so a
+  normalizer of your own is never handed a container's items.
+- In a container, a class **subclassing** one of the interfaces is tagged without being told; a
+  class that only has their methods is not, and joins nothing until a tag puts it there — see
+  [application.md](application.md).