Problem

The persistence→HTTP serialization seam was shallow and leaked. Every list handler assembled its response envelope from raw ORM rows and lied to the type checker:

return typing.cast("schemas.Decks", {"items": objects})

A dict of ORM objects is not a schemas.Decks — the cast just silenced ty. The envelope shape (items) was duplicated at every call site, and the real ORM→Pydantic conversion happened invisibly inside FastAPI's response_model re-validation. Single-object handlers had the same leak in miniature (typing.cast("schemas.Deck", instance)).

Change

Port of modern-python/litestar-sqlalchemy-template#29, adapted to this repo's idiom and extended to converge on the litestar template's end state: no casts anywhere, every handler routed through its schema.

Introduce a deep generic Collection[T] seam in app/schemas.py:

class Collection[T: Base](Base):
    items: list[T]

    @classmethod
    def from_models(cls, objects: Iterable[object]) -> Self:
        return cls.model_validate({"items": list(objects)})

class Cards(Collection[Card]): pass
class Decks(Collection[Deck]): pass

The ORM→schema coercion now happens once, behind a small interface. model_validate (param typed Any) absorbs the coercion honestly, so the leaky casts disappear:

• Collection handlers → schemas.Xs.from_models(objects)
• Single-object handlers → schemas.X.model_validate(instance)

Decks/Cards stay as named subclasses, so OpenAPI schema names are unchanged.

CLAUDE.md's convention is updated to mandate explicit ORM→schema conversion and forbid typing.cast.

Adaptation notes

• The litestar PR removed four # ty: ignore[invalid-argument-type] suppressions on schemas.Decks(items=...) constructors. This repo had none — instead it used typing.cast(..., {"items": objects}), the local form of the same leak. from_models replaces those.
• Litestar already used model_validate on single-object handlers, so its PR left them untouched. This repo used casts there, so killing them is what makes this repo converge on the litestar template's shape.
• The return_dto=PydanticDTO cleanup from the litestar PR has no FastAPI equivalent.

Contract & tests

• Wire contract unchanged — {items: [...]}, same field names, same schema names.
• ruff format --check, ruff check, ty check all clean.
• 19 passed, 100% coverage held.