refactor: deepen ORM→HTTP serialization behind a Collection seam

[lesnik512]

Problem

The persistence→HTTP serialization seam was shallow and leaked. Every list handler built its response envelope from raw ORM rows:

return schemas.Decks(items=objects)  # ty: ignore[invalid-argument-type]

— each of the four carrying a ty: ignore for the Sequence[Model] → list[Schema] static mismatch. get_card separately carried a stray return_dto=PydanticDTO[schemas.Card] on top of a manual model_validate.

Change

Introduce a deep 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. Routing through model_validate (param typed Any) absorbs the coercion cleanly, so all four ty: ignore[invalid-argument-type] suppressions are removed. List handlers call schemas.Xs.from_models(objects); get_card drops its redundant DTO and now returns through its schema like every other handler.

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

Contract & tests

• Wire contract unchanged — {items: [...]}, no audit timestamps, same schema names.
• Single-object handlers unchanged (schemas.X.model_validate(instance) was already typed).
• The seam is exercised by every list-endpoint test; existing HTTP tests are the test surface. 19 passed, 100% coverage held.

🤖 Generated with Claude Code