fix: honor Event(internal=True) and give internal events from outside a step the external contract

[fgmacedo]

Por quê

#663 makes Event(..., internal=True) reach the queue (#655). With it applied, a declared-internal event triggered from outside a callback returned None, was lost on a fresh async machine, and raise_(delay=50) fired at 0 ms (script below, 4 of 4 checks wrong on develop + #663). Closes #655.

O que muda

• An internal event (raise_(), send(internal=True), Event(internal=True)) joins the internal queue only when raised from a callback while the machine runs a step. Triggered from outside, it goes to the external queue: the caller gets the callback result, the exception, or TransitionNotAllowed on a StateMachine, and the async caller gets a future.
• The first await sm.go() on a fresh async machine with a declared-internal go now runs after the initial state is entered instead of being dropped.
• delay together with internal raises InvalidDefinition, whether declared (Event(..., delay=50, internal=True)), sent, raised (raise_(delay=50)) or loaded from an SCXML/JSON/YAML <send target="#_internal" delay=...> (rejected at load time, and by the JSON Schema). SCXML forbids the combination; previously the delay was silently ignored. An explicit send(..., internal=False) overrides an internal=True declaration.
• Each external event is now followed by its macrostep before the next queued external event is taken. Before, an internal event raised while handling one external event ran after the other external events already queued.
• The "running a step" flag is a ContextVar holding the engine, so it is right per thread, per asyncio task and per machine: a coroutine or thread sending while another runs the loop, or a callback raising on another machine, gets the external contract.
• Keeps @chiliec's commit from fix: honor Event(internal=True) when the event is triggered #663 with authorship (ec8ce36).

Evidência

evidence.py, run with uv run python evidence.py on each commit:

import asyncio
from statemachine import Event, State, StateChart

class Beacons(StateChart):
    dark = State(initial=True)
    lit = State(final=True)
    light = Event(dark.to(lit, on="kindle"), internal=True)
    def kindle(self): return "kindled"

class AsyncBeacons(Beacons):
    async def kindle(self): return "kindled"

class Relay(StateChart):
    dark = State(initial=True)
    lit = State(final=True)
    besieged = State(final=True)
    signal = dark.to.itself(internal=True, on="relay")
    light = dark.to(lit)
    siege = dark.to(besieged)
    def relay(self):
        self.raise_("light")
        self.send("siege")

print("sync  sm.light():", repr(Beacons().light()))
async def first_await():
    sm = AsyncBeacons()
    return await sm.light(), sorted(sm.configuration_values)
print("async first await:", asyncio.run(first_await()))
sm = Relay(); sm.send("signal"); print("raised before queued external:", sorted(sm.configuration_values))
try:
    Beacons().raise_("light", delay=50); print("raise_(delay=50): accepted")
except Exception as e:
    print("raise_(delay=50):", type(e).__name__)

== before (develop + #663, ec8ce36)
sync  sm.light(): None
async first await: (None, ['dark'])
raised before queued external: ['besieged']
raise_(delay=50): accepted

== after (this branch)
sync  sm.light(): 'kindled'
async first await: ('kindled', ['lit'])
raised before queued external: ['lit']
raise_(delay=50): InvalidDefinition

$ timeout 300 uv run pytest -n 4 --cov=statemachine --cov-branch --cov-report=term-missing:skip-covered
TOTAL    6074      0   1884      0   100%
2322 passed, 1 skipped, 44 xfailed
$ uv run pytest tests/test_event_ordering.py   # with the engines of develop
4 failed, 16 passed   # the new one-external-event-per-macrostep cases

New tests: tests/test_internal_triggers.py (46 cases, both engines via sm_runner) and tests/test_event_ordering.py::test_what_an_external_event_enables_runs_before_the_next_external_event. W3C SCXML suite passes on both engines.

Não verificado

• Benchmarks (--benchmark-autosave) not run. A review probe measured 2000 queued external events with one guarded eventless transition: about 27-31% slower (51 ms vs 40 ms sync), since eventless transitions are now checked after every external event.
• Free-threaded Python 3.14 (thread_inherit_context): a thread spawned from inside a step would inherit the "running a step" flag; only GIL builds were run.
• _event.type in SCXML still reports "internal" for a declared-internal event triggered from outside, even though it is queued externally.
• #664 (event deferral) touches the same loops and will need a rebase after this merges.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (0de640a) to head (e03da9c).

Additional details and impacted files

@@            Coverage Diff            @@
##           develop      #668   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           52        52           
  Lines         5651      5672   +21     
  Branches       888       891    +3     
=========================================
+ Hits          5651      5672   +21     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
7 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