fix: honor msgspec rename in schema_dump + make OffsetPagination runtime-introspectable

[cofin]

Summary

Fixes two silent-divergence bugs between declared schema contract and wire output:

• Fixes schema_dump ignores msgspec rename meta — Struct with rename="camel" emits snake_case field names #418 — sqlspec.utils.serializers.schema_dump now honors msgspec.Struct rename= meta. Structs declared with rename="camel" / "kebab" / "pascal" / callable now emit the renamed wire names instead of the Python attribute names.
• Fixes OffsetPagination has empty runtime __annotations__ — Litestar OpenAPI schema generator produces empty schema for paginated responses #419 — sqlspec.core.filters.OffsetPagination is now a msgspec.Struct. Runtime __annotations__ survive mypyc-compiled wheels, restoring Litestar OpenAPI schema generation for OffsetPagination[T] responses and unblocking downstream client generators (@hey-api/openapi-ts, etc.).

Implementation

#418 — schema_dump rename fix

_dump_msgspec_fields / _dump_msgspec_excluding_unset now iterate msgspec.structs.fields(type(value)) and use field.encode_name for the dict key + field.name for the attribute lookup. Same pattern already established by sqlspec.utils.type_guards.get_msgspec_rename_config.

#419 — OffsetPagination runtime types

Two-layer fix:

1. Root cause: Convert OffsetPagination to msgspec.Struct(Generic[T]). msgspec's metaclass captures annotations at class-creation time so they survive mypyc, and Litestar natively recognizes msgspec.Struct subclasses for OpenAPI schema generation.

2. Mypyc-compat split: Wheel validation surfaced TypeError: mypyc classes can't have a metaclass — mypyc refuses to compile any class with a non-default metaclass. OffsetPagination moved to sqlspec/core/_pagination.py (added to the mypyc exclude list) and re-exported from sqlspec.core.filters. The public import path is unchanged. Hot-path filter classes in filters.py continue to compile.

3. Defense-in-depth: Register _OffsetPaginationSchemaPlugin (an OpenAPISchemaPlugin) in SQLSpecPlugin that emits {items: array<T>, limit, offset, total} explicitly — guards against any future Litestar/msgspec drift that would break auto-detection.

4. Cleanup: Delete the now-redundant _encode_offset_pagination type_encoder — msgspec.Struct is encoded natively by Litestar's default serialization to the same JSON shape.

Behavior changes

Converting OffsetPagination to msgspec.Struct changes three dunder behaviors (called out in docs/changelog.rst):

• __eq__ is now field-wise (was identity)
• __hash__ is None (msgspec default for non-frozen Structs — was id-based)
• __repr__ is informative OffsetPagination(items=..., limit=..., offset=..., total=...)

Test plan

• uv run pytest tests/unit/ tests/integration/extensions/litestar/ --ignore=tests/unit/adapters — 4423 passed, 26 skipped, 0 failed
• uv run ruff check sqlspec tests — all checks passed
• Red phase confirmed: 5/6 rename tests fail on snake_case keys before fix; OpenAPI test fails with Item not in OpenAPI components: set() before fix
• Green phase confirmed: every task passes tests immediately after the matching fix
• HATCH_BUILD_HOOKS_ENABLE=1 uv build --wheel — compiled wheel produced filters.cpython-310-x86_64-linux-gnu.so (compiled) + _pagination.py (uncompiled)
• Issue OffsetPagination has empty runtime __annotations__ — Litestar OpenAPI schema generator produces empty schema for paginated responses #419 reproducer against installed compiled wheel prints components: ['Item', 'OffsetPagination___main__.Item_'] and OK: Item registered, response schema non-empty
• Docs recipes spot-check — docs/recipes/service_layer.rst uses keyword-arg OffsetPagination(items=..., limit=..., offset=..., total=...) construction, wire-compatible with msgspec.Struct, no changes needed

Commits

8 commits on fix/annotation-thing, Red-Green-Refactor per chapter:

284237d4 docs(changelog): add schema wire correctness release notes
33186c86 refactor(core): move OffsetPagination to _pagination.py (mypyc compat)
774287a3 feat(litestar): register _OffsetPaginationSchemaPlugin for OpenAPI
ef9c1366 refactor(litestar): remove dead _encode_offset_pagination
93dc6c9f fix(filters): convert OffsetPagination to msgspec.Struct
209e13c6 test(litestar): add failing OpenAPI schema assertion
4c1aad07 fix(serializers): honor msgspec rename meta in schema_dump
3cf93b3f test(serializers): add failing rename matrix for schema_dump

Fixes #418
Fixes #419

[wpuziewicz]

LGTM