fix: run the effect of an explicit initial transition and register it as the only initial

[fgmacedo]

Refs #587
Refs #692

Builds on #693 (merged), which makes default entry run the initial transition it chose.

Why

d.to(d.d2.d21.d212, initial=True, on="init_action") inside a compound entered the deep target, but the factory also registered the automatic document-order initial transition d -> d1, so the state held two initial transitions, and the on= effect of the explicit one never ran.

What changes

• factory.py: when a non-parallel compound already declares an explicit initial transition, no default initial transition is added and no child is flagged initial by document order. Two explicit initial transitions on the same state raise InvalidDefinition.
• Engines (sync and async): the initial effect is called with the same on_error as transition on content, so in a StateChart an exception in it becomes error.execution at block level and entry completes, instead of aborting the microstep. During error.execution handling it propagates, as transition on content does.
• docs/states.md: new "Explicit initial transition" section with a doctest (deep target, effect order, re-entry).
• Tests: tests/test_statechart_initial_transition.py (sync and async via sm_runner) and a native YAML case in tests/io/test_native_behavior.py.

Behavior change: a Python-API chart whose first child was only "reachable" through the automatic initial transition (never actually entered, since the explicit one won) now fails the reachability check with InvalidDefinition.

Evidence

• New tests fail before and pass after: 15 fail on main, 10 fail on top of fix: enter history states by default without running the incoming effect twice #693 alone (duplicate registration, two explicit initials, error handling, native format); all pass here.
• Effect order: enter d, init_action, enter d2, enter d21, enter d212, also on re-entry and in subclasses; initial into a history state runs the effect once per entry.
• Full suite rebased on main (75c9181): 2992 passed, 26 skipped, 126 xfailed; branch coverage 100%; ruff and mypy clean.
• PSSM suite (tests/uml/pssm/, xfail_strict): 150 passed, 1 skipped, 82 xfailed; no case changes status with this PR.
• Adversarial review, 1 round by a fresh subagent: nothing material. Minor findings, all pre-existing on main and left out of scope: an explicit initial transition silently wins over a contradictory initial=True child (rejecting it breaks W3C cases, because the SCXML reader flags deep initial targets as initial); diagrams draw the first child instead of the explicit initial target; an initial target outside the compound and an explicit initial on a parallel state are not validated; a subclass adding an explicit initial to an inherited compound now raises "more than one initial transition" instead of being silently ignored.

Not verified

• Diagram rendering of an explicit initial transition (still points at the first child, pre-existing).
• No release notes entry: there is no 3.3.0 notes file yet.
• on_init_<state> convention and a root-level initial effect are out of scope (they wait for an API decision on UML initial transitions: target a nested descendant directly and support on_init_<state> actions #587).

[codecov]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #694   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           53        53           
  Lines         5900      5904    +4     
  Branches       939       941    +2     
=========================================
+ Hits          5900      5904    +4     

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
1 New issue
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