KeyedRateLimitRef.key_fn receives an untyped payload dict rather than the validated model

[rcbevans]

KeyedRateLimitRef.key_fn is typed Callable[[dict[str, object]], str], and the dict it receives is the raw job-row payload, not the actor's validated payload model. In the consumer, the limiter is resolved with payload=job.payload — the JSON straight off the row — and the payload is validated against payload_type further down the same dispatch, after admission control has already run.

For a library this strict about typing everywhere else, that's a surprising seam, and it has consequences beyond ergonomics:

• Pydantic defaults don't apply. A key field with a default that wasn't present in the serialized payload is simply missing from the dict, even though the attribute is populated on the model the handler receives. key_fn and the handler then disagree about the same field.
• Aliases don't apply. With Field(alias="providerId"), the model exposes provider_id while the raw dict has providerId. key_fn has to know the wire name, so the routing key is coupled to serialization rather than to the model.
• Failures surface in the wrong layer. If the field is absent or the wrong shape, the KeyError/TypeError is raised inside rate-limit resolution rather than as a payload-validation error, so an invalid payload looks like a limiter fault.
• No type checking at the point it matters most. payload["provider"] is exactly the kind of expression a rename should break at check time and doesn't.

Today I keep the keyed field mandatory, never aliased, never defaulted, and always a plain scalar — an invariant that nothing enforces and that a future model refactor will quietly violate.

What I'd rather have is key_fn receiving the validated model:

KeyedRateLimitRef(
    base_name="api-per-tenant",
    key_fn=lambda p: p.tenant_id,   # typed, defaults and aliases applied
    capacity=10,
    refill_per_second=1.0,
)

The validated payload is constructed on the same dispatch anyway, so the data is available; the question is ordering, not availability. (Same argument applies to KeyedReservationRef.key_fn, which shares the signature.)

Open questions:

• Is limits-before-validation deliberate — don't pay model_validate for a job you might not admit, or don't let a malformed payload consume a token? Both are defensible, and if that's the intent then moving validation earlier is the wrong fix.
• If the ordering has to stay, would a typed opt-in work — the ref declaring the payload type so key_fn gets a validated model, falling back to the raw dict otherwise? That keeps the fast path and gives correctness to callers who want it.
• Failing both, a docstring note that key_fn sees the pre-validation wire form, and that defaults and aliases therefore do not apply, would at least make the trap visible. Keyed rate-limit follow-ups: accept str subclasses from key_fn; surface keyed limits in the admin UI #32 tightened the return side of key_fn; this is the argument side.

[rcbevans]

Correcting myself: the central claim in this issue as filed is wrong, and I'd rather say so than leave it standing.

I asserted that because key_fn receives the raw row payload, Pydantic defaults and aliases don't apply. Both parts are wrong:

• Defaults do apply. EnqueueItem.payload is already a constructed model instance, so Pydantic materialised defaults at construction time, before the dict was ever written. enqueue_batch additionally validates every payload up front (client/_jobs.py:437).
• Aliases aren't an issue either. There's no by_alias anywhere in the codebase, so the stored dict is keyed by field name — exactly what p["field_name"] expects.

I read _consumer.py:310 passing payload=job.payload into the limiter and :357-360 calling model_validate afterwards, and concluded the limiter therefore saw unvalidated data. The re-validation on dispatch is defence-in-depth against a row written by a different code version, not the first validation. My mistake.

What I still think holds, reduced to the part that survives:

The typing gap. key_fn: Callable[[dict[str, object]], str] hands you an untyped dict at the one point where you're deciding how a job gets scheduled. p["provider"] is exactly the expression a field rename should break at check time and doesn't — it breaks at dispatch, in the limiter, on a job that's already been accepted. For a library this consistent about typed surfaces elsewhere, that seam stands out, and passing the validated model (or a typed opt-in variant) would close it.

A narrow real divergence: schema evolution. A job enqueued before a model gained a field, dispatched after the deploy that added it, has a stored dict without that key. The handler's model_validate supplies the default; key_fn sees it missing and raises. With terminal jobs retained ~30d and rolling deploys, that window is real, if small — and it's a genuinely confusing failure, since the limiter raises on a payload the handler would have accepted.

So: narrower issue than filed. I've retitled it accordingly. If the typing argument isn't compelling on its own, closing this is entirely reasonable — the original framing was the load-bearing part and it didn't hold up.