feat: protocol-based invoke architecture with SCXML spec compliance

Refactor invoke mechanism to use Python Protocols, enabling any callable
or class with a run() method to be used as State(invoke=handler).

Key changes:
- InvokeConfig/InvokeContext/Invoker Protocol in statemachine/invoke.py
- StateChartInvoker adapter for child StateChart invocations
- SCXMLInvoker in io/scxml/invoke.py for src/srcexpr/content resolution
- done.invoke uses invokeid per SCXML spec (prefix matching in is_same_event)
- One external event per macrostep iteration (SCXML spec compliance)
- Skip unknown transition targets gracefully in create_machine_class_from_definition
- Error handling for invoke param evaluation (sends error.execution)
- Child SM lookup via handler._child_sm during execution
- Move _assert_passed into _run_scxml_testcase for --upd-fail coverage
- Add fail markers for optional SCXML tests and test276.async

Author: fgmacedo

statemachine/engines/async_.py

@@ -312,6 +312,19 @@ async def _run_microstep(self, enabled_transitions, trigger_data):  # pragma: no
         except Exception as e:
             self._handle_error(e, trigger_data)
 
+    async def enter_initial_configuration(self):
+        """Enter the initial state configuration without starting the processing loop.
+
+        Async override of the base method for use by invoke's two-phase activation.
+        """
+        if self.sm.current_state_value is not None:
+            return
+        from ..event import BoundEvent
+
+        trigger_data = BoundEvent("__initial__", _sm=self.sm).build_trigger(machine=self.sm)
+        transitions = self._initial_transitions(trigger_data)
+        await self._enter_states(transitions, trigger_data, OrderedSet(), OrderedSet())
+
     async def activate_initial_state(self):
         """Activate the initial state.
 
@@ -399,6 +412,11 @@ async def processing_loop(  # noqa: C901
                         # transitions can be processed while we wait.
                         break
 
+                    # Forward delayed cross-session events to their target
+                    if external_event.forward_target:
+                        self._forward_to_target(external_event)
+                        continue
+
                     logger.debug("External event: %s", external_event.event)
 
                     # Handle invoke finalize and autoforward

statemachine/engines/base.py

@@ -138,6 +138,33 @@ def cancel_event(self, send_id: str):
         """Cancel the event with the given send_id."""
         self.external_queue.remove(send_id)
 
+    def _forward_to_target(self, trigger_data: TriggerData):
+        """Forward an event to a cross-session target instead of processing it.
+
+        Called by the processing loop when ``trigger_data.forward_target`` is set.
+        This supports delayed cross-session sends: the event sits on the child's
+        queue with a delay, and when it expires the processing loop forwards it
+        to the named target.
+        """
+        target = trigger_data.forward_target
+        event_name = str(trigger_data.event)
+        if target in ("#_parent", "parent"):
+            parent_sm = getattr(self.sm, "_parent_sm", None)
+            if parent_sm is not None:
+                child_invokeid = getattr(self.sm, "_invokeid", None)
+                parent_sm.send(
+                    event_name,
+                    *trigger_data.args,
+                    invokeid=child_invokeid,
+                    **trigger_data.kwargs,
+                )
+            else:
+                self.sm.send("error.communication", internal=True)
+        elif target == "#_child":
+            self.invoke_manager.send_to_child(event_name, **trigger_data.kwargs)
+        else:
+            logger.warning("Unknown forward_target: %s", target)
+
     def _on_error_handler(self) -> "Callable[[Exception], None] | None":
         """Return a per-block error handler, or ``None``.
 
@@ -188,6 +215,19 @@ def start(self):
 
         BoundEvent("__initial__", _sm=self.sm).put()
 
+    def enter_initial_configuration(self):
+        """Enter the initial state configuration without starting the processing loop.
+
+        Used by invoke to split activation into two phases: enter initial states
+        (which runs datamodel entry actions), then apply invoke params, then start
+        the processing loop.
+        """
+        if self.sm.current_state_value is not None:
+            return
+        trigger_data = BoundEvent("__initial__", _sm=self.sm).build_trigger(machine=self.sm)
+        transitions = self._initial_transitions(trigger_data)
+        self._enter_states(transitions, trigger_data, OrderedSet(), OrderedSet())
+
     def _initial_transitions(self, trigger_data):
         empty_state = State()
         configuration = self.sm._get_initial_configuration()

statemachine/engines/sync.py

@@ -79,7 +79,7 @@ def processing_loop(self, caller_future=None):  # noqa: C901
         first_result = self._sentinel
         try:
             took_events = True
-            while took_events:
+            while took_events and not self.sm.is_terminated:
                 self.clear_cache()
                 took_events = False
                 # Execute the triggers in the queue in FIFO order until the queue is empty
@@ -139,6 +139,11 @@ def processing_loop(self, caller_future=None):  # noqa: C901
                         # transitions can be processed while we wait.
                         break
 
+                    # Forward delayed cross-session events to their target
+                    if external_event.forward_target:
+                        self._forward_to_target(external_event)
+                        continue
+
                     logger.debug("External event: %s", external_event.event)
 
                     # Handle invoke finalize and autoforward
@@ -165,10 +170,21 @@ def processing_loop(self, caller_future=None):  # noqa: C901
                             self.clear()
                             raise
 
+                        # Per SCXML spec: process ONE external event per macrostep,
+                        # then loop back to handle eventless transitions, internal
+                        # events, and invoke spawning before the next external event.
+                        break
+
                     else:
                         if not self.sm.allow_event_without_transition:
                             raise TransitionNotAllowed(external_event.event, self.sm.configuration)
 
+                # If no events were processed but there are pending events
+                # on the external queue (e.g., delayed timeouts in SCXML tests),
+                # keep the loop alive so child sessions can send events back.
+                if not took_events and not self.external_queue.is_empty():
+                    took_events = True
+
         finally:
             self._processing.release()
         return first_result if first_result is not self._sentinel else None

statemachine/event.py

@@ -95,7 +95,22 @@ def __repr__(self):
         )
 
     def is_same_event(self, *_args, event: "str | None" = None, **_kwargs) -> bool:
-        return self == event
+        if self == event:
+            return True
+        if event is not None:
+            event_str = str(event)
+            self_dot = str(self).replace("_", ".")
+            event_dot = event_str.replace("_", ".")
+
+            # Exact match with dot/underscore normalization
+            if self_dot == event_dot:
+                return True
+
+            # SCXML prefix matching: descriptor "done.invoke.active" matches
+            # actual event "done.invoke.active.abc123"
+            if event_dot.startswith(self_dot + "."):
+                return True
+        return False
 
     def _add_callback(self, callback, grouper: CallbackGroup, is_event=False, **kwargs):
         if self._transitions is None:
@@ -121,14 +136,26 @@ def __get__(self, instance, owner):
             return self
         return BoundEvent(id=self.id, name=self.name, delay=self.delay, _sm=instance)
 
-    def put(self, *args, send_id: "str | None" = None, invokeid: "str | None" = None, **kwargs):
+    def put(
+        self,
+        *args,
+        send_id: "str | None" = None,
+        invokeid: "str | None" = None,
+        forward_target: "str | None" = None,
+        **kwargs,
+    ):
         # The `__call__` is declared here to help IDEs knowing that an `Event`
         # can be called as a method. But it is not meant to be called without
         # an SM instance. Such SM instance is provided by `__get__` method when
         # used as a property descriptor.
         assert self._sm is not None
         trigger_data = self.build_trigger(
-            *args, machine=self._sm, send_id=send_id, invokeid=invokeid, **kwargs
+            *args,
+            machine=self._sm,
+            send_id=send_id,
+            invokeid=invokeid,
+            forward_target=forward_target,
+            **kwargs,
         )
         self._sm._put_nonblocking(trigger_data, internal=self.internal)
         return trigger_data
@@ -139,6 +166,7 @@ def build_trigger(
         machine: "StateChart",
         send_id: "str | None" = None,
         invokeid: "str | None" = None,
+        forward_target: "str | None" = None,
         **kwargs,
     ):
         if machine is None:
@@ -150,6 +178,7 @@ def build_trigger(
             event=self,
             send_id=send_id,
             invokeid=invokeid,
+            forward_target=forward_target,
             args=args,
             kwargs=kwargs,
         )

statemachine/event_data.py

@@ -30,6 +30,16 @@ class TriggerData:
     execution_time: float = field(default=0.0)
     """The time at which the :ref:`Event` should run."""
 
+    forward_target: "str | None" = field(compare=False, default=None)
+    """When set, the processing loop forwards this event to the named target
+    (e.g. ``"#_parent"``, ``"#_child"``) instead of processing it normally.
+
+    Used for delayed cross-session sends: the event sits on the child's queue
+    with a delay, and when the delay expires it is forwarded to the target.
+    If the child terminates first, the event is never processed — automatic
+    cancellation per SCXML spec.
+    """
+
     model: Any = field(init=False, compare=False)
     """A reference to the underlying model that holds the current :ref:`State`."""
 
@@ -57,7 +67,7 @@ class EventData:
     trigger_data: TriggerData
     """The :ref:`TriggerData` of the :ref:`event`."""
 
-    transition: "Transition"
+    transition: "Transition | None"
     """The :ref:`Transition` instance that was activated by the :ref:`Event`."""
 
     state: "State" = field(init=False)