feat: add event deferral to states

[SahilRajputdotexe]

This adds UML-style event deferral. A state can list events it wants to hold back with State(defer=[...]). If an event arrives, no transition handles it, and every active atomic state defers it, the engine queues it instead of dropping it (or raising TransitionNotAllowed). Once the machine reaches a configuration that no longer defers the event, the queued events go back to the external queue in the order they were sent, with their original arguments.

It is useful when an event can legitimately show up before the machine is ready for it, so callers don't have to buffer it themselves.

class Council(StateChart):
    gathering = State(initial=True, defer=["speak"])
    deliberating = State()
    decided = State(final=True)

    convene = gathering.to(deliberating)
    speak = deliberating.to(decided)

sm = Council()
sm.send("speak")    # queued, still in `gathering`
sm.send("convene")  # leaves `gathering`, `speak` is replayed -> `decided`

Details:

• Compound states defer for their children (class mordor(State.Compound, defer=["rest"])). In parallel states the event is only deferred if all regions defer it.
• on_defer / on_replay callbacks, inline or by naming convention (on_defer_event, on_defer_<state>, on_replay_event, on_replay_<state>).
• StateChart gets deferred_events, pending_deferred_event_ids, is_event_deferred() and clear_deferred_queue().
• Final states can't defer. The queue is cleared when the machine terminates and is not pickled.
• validate_deferred_events = True (off by default) checks the ids against the declared events.
• Works in both the sync and async engines.

I added a docs page (docs/deferral.md), entries in the states and validations pages, and a 3.3.0 release notes file since this is a new feature and 3.2.2 is a bug fix release. Happy to move the notes if you prefer another place.

Tests are in tests/test_statechart_deferral.py, most of them run on both engines through sm_runner. The full suite passes with 100% coverage, and ruff and mypy are clean. Lint and tests pass on my fork for Python 3.10 to 3.14.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud