Summary

next_available_time returned datetime.datetime.min as an implicit sentinel
for "this key has never been used." The return type was datetime.datetime with
no documentation, so callers could not distinguish a "never used" key from a key
that was genuinely last used near the epoch. Mixing the sentinel with a
timezone-aware datetime also raised TypeError.

Changes

• throttle_controller/simple.py / throttle_controller/protocol.py:
  Change the return type of next_available_time from datetime.datetime to
  datetime.datetime | None. Return None when the key has never been used.
• throttle_controller/simple.py: Update wait_time_for to treat None as
  zero wait (i.e. the key is immediately available).
• tests/test_simple.py: Update test_next_available_time to assert is None
  for an unused key and to check the non-None path with a type-safe assertion.

Validation

• uv run poe format — reformatted
• uv run poe check — all checks pass (ruff + mypy)
• uv run pytest — all tests pass
  (pre-existing test_throttling timing flakiness is unrelated to this change)

Trade-offs

This is a breaking change for callers that compare next_available_time(key)
against datetime.datetime.min or treat the return value as always non-None.
Type checkers will surface these sites as errors. The default wait_if_needed
path is unaffected because it already guards on _has_ever_used.