feat(ratelimit)!: typed key_fn with validated payloads, payload_type required (#60)

[rcbevans]

Summary

Makes key_fn on KeyedRateLimitRef and KeyedReservationRef always receive the validated Pydantic model instead of the raw dict from the job row. payload_type is now a required field on both refs, a .typed() classmethod provides compile-time type safety, and the consumer unconditionally passes the validated BaseModel to the registry — no raw-dict fallback path.

Issue addressed

Closes #60 — key_fn receives the validated model, not the pre-validation wire dict.

Implementation

payload_type is now required. Both KeyedRateLimitRef and KeyedReservationRef declare payload_type: type[BaseModel] with no default. Construction without it raises ValidationError. The field declares the model class the registry validates the payload against before calling key_fn.

key_fn signature: Callable[[BaseModel], str]. The callable always receives the validated model instance — with Pydantic defaults, aliases, and validators applied. There is no untyped path; key_fn never sees a raw dict.

.typed() classmethod on both refs: generic over P: BaseModel, accepts payload_type: type[P] and key_fn: Callable[[P], str] so the caller's lambda is type-checked against the concrete model's attributes at static-analysis time. The stored key_fn field is typed as Callable[[BaseModel], str] (the registry guarantees the runtime type via isinstance).

RateLimitRegistry._resolve_key_fn_arg() — shared by _resolve_rate_limit_name and _resolve_reservation_name. Three cases:

• Same model type (isinstance(payload, ref.payload_type) is True): zero-cost pass-through — the exact same object is passed to key_fn, no re-validation.
• Different BaseModel type: re-validate via ref.payload_type.model_validate(payload.model_dump()). Converts the actor's model into the ref's declared model, applying the ref's aliases/defaults/validators. A ValidationError from this surfaces as a payload error, not a limiter fault.
• Raw dict (direct callers, tests): validate via ref.payload_type.model_validate(dict).

_consumer.py — the validated_payload fallback is moved before acquire_for_actor so the model is always available. payload=validated_payload (the BaseModel) is passed unconditionally — no gating, no job.payload (raw dict) path. A ValidationError from an invalid payload now surfaces before a rate-limit token is consumed.

acquire_for_actor signature: payload parameter widened to dict[str, object] | BaseModel | None to accept both forms (dict for direct callers, BaseModel for the dispatch path).

Breaking changes

This is a breaking change — intentional for a pre-1.0 library heading to 1.0. No backward-compat shims.

• payload_type is required. Construction without it raises ValidationError. No None default, no optional.
• key_fn receives a BaseModel, not a dict. Existing implementations that access raw dict keys (p["tenantId"]) must be updated to model attributes (p.tenant_id). This is the point — the typed approach is strictly better: Pydantic defaults populate fields absent from the serialized payload, aliases map wire names to model attributes, and validation errors surface as ValidationError (a payload error) rather than KeyError/AttributeError (a limiter fault).
• Validation before token consumption. An invalid payload now raises ValidationError before acquire_for_actor is called, so no rate-limit token is consumed on a job that will never run. Previously, the raw dict was passed to key_fn and a KeyError could occur after token acquisition.

Test coverage

File	Coverage
tests/test_ratelimit_refs.py	.typed() classmethod: stores payload_type, construction without payload_type raises ValidationError, key_fn receives model not dict, backend parameter, default fields, aliases, extra=forbid validation. Both refs.
tests/test_ratelimit_keyed_rate_limits.py	Helper migrated to .typed(). Typed _resolve_rate_limit_name: dict→model validation, pydantic defaults applied, alias resolution, BaseModel same-type pass-through (identity check), BaseModel wrong-type re-validation, ValidationError propagation, acquire_for_actor with BaseModel and dict payloads.
tests/test_ratelimit_keyed_refs.py	Helper migrated to .typed(). Typed _resolve_reservation_name: same coverage as rate limits, plus wrong-model-type raises ValidationError (not AttributeError).
tests/test_keyed_reservation_hardening.py	_keyed_ref helper migrated to .typed().
tests/test_ratelimit_keyed_rate_limits_pg.py	Direct constructions migrated to .typed().
tests/test_ratelimit_keyed_refs_pg.py	Direct constructions migrated to .typed().
tests/test_consumer.py	Consumer passes validated BaseModel (not raw dict) to acquire_for_actor; validation failure before acquire means zero resources acquired; KeyedRateLimitRef.key_fn receives BaseModel at the consumer level.
tests/test_ratelimit_composition.py	Ref constructions migrated to .typed().
tests/test_di_validate.py	Ref constructions migrated to .typed().
tests/test_worker_di_bootstrap.py	Ref construction migrated to .typed().
tests/test_actor.py	Ref construction migrated to .typed().
tests/test_queue_concurrency_cap.py	Ref constructions migrated to .typed(); saturation test passes validated payload.
tests/web_admin/test_ops.py	Ref construction migrated to .typed().
tests/e2e/actors.py	deliver_tenant_webhook migrated to .typed(). New deliver_typed_tenant_webhook actor with Field(alias="tenantId") + serialize_by_alias=True — proves the validated model (not raw dict) reaches key_fn end-to-end.
tests/e2e/test_keyed_rate_limit.py	New e2e test: typed keyed rate limit with aliased payload, per-tenant independence.
tests/e2e/worker_entry.py	Registers new typed actor.

Documentation

• docs/guides/rate-limiting.md — all key_fn examples updated from dict access (p["tenant_id"]) to model attributes (p.tenant_id). Added .typed() usage examples with alias and default field demonstrations. Documented payload_type requirement and ValidationError vs KeyError semantics.
• docs/architecture.md — dispatch integration section updated to describe validated payload model flow to acquire_for_actor.
• docs/specs/2026-07-29-ratelimit-typing.md — full design spec for this change.

---

Closes #60