python-statemachine 3.1.2__py3-none-any.whl → 3.2.0__py3-none-any.whl

statemachine/io/evaluators.py

@@ -0,0 +1,275 @@
+"""Evaluation strategies for statechart datamodel expressions and scripts.
+
+An :class:`Evaluator` turns the raw expression/script strings carried by the
+neutral IR (:mod:`statemachine.io.model`) into callables, deciding *how* they are
+evaluated:
+
+- :class:`RestrictedEvaluator` (secure default): compiles expressions with the
+  AST-whitelist evaluator (:func:`statemachine.spec_parser.parse_expr`), which
+  cannot reach builtins, dunder attributes, or arbitrary calls. ``<script>`` and
+  raw-Python evaluation are rejected because they are arbitrary code.
+- :class:`PythonEvaluator` (opt-in, ``trusted=True``): preserves the legacy
+  behavior of evaluating expressions and scripts as arbitrary Python via
+  ``eval``/``exec``.
+
+The restricted evaluator validates the *structure* of an expression at compile
+time (a violation raises :class:`~statemachine.exceptions.InvalidDefinition`),
+but name resolution and value computation still happen at call time, so runtime
+errors (``NameError``, ``TypeError``) keep flowing to ``error.execution`` as
+before.
+
+This module is format-neutral: it is shared by the SCXML, JSON and YAML readers.
+See the :mod:`statemachine.io.scxml` package docstring and the GHSA-v4jc-pm6r-3vj8
+advisory for the rationale.
+"""
+
+import ast
+import html
+import re
+from collections.abc import Callable
+from inspect import isawaitable
+from typing import Any
+from typing import Protocol
+
+from ..dispatcher import callable_method
+from ..event import _event_data_kwargs
+from ..exceptions import InvalidDefinition
+from ..spec_parser import InState
+from ..spec_parser import parse_expr
+
+#: Attributes that must never be exposed to or overwritten by datamodel
+#: expressions (engine internals and SCXML system variables).
+protected_attrs = _event_data_kwargs | {"_sessionid", "_ioprocessors", "_name", "_event"}
+
+
+_COND_REPLACEMENTS = {
+    "true": "True",
+    "false": "False",
+    "null": "None",
+    "===": "==",
+    "!==": "!=",
+    "&&": "and",
+    "||": "or",
+}
+_COND_PATTERN = re.compile(r"\b(?:true|false|null)\b|===|!==|&&|\|\|")
+
+
+def normalize_cond(cond: str) -> str:
+    """Normalize a JavaScript-like condition to Python syntax.
+
+    Decodes XML entities (e.g. ``&lt;``) and maps ``true``/``false``/``null`` and
+    the ``===``/``!==``/``&&``/``||`` operators to their Python equivalents. This
+    is primarily an SCXML (ECMAScript datamodel) concern; for Python-style
+    expressions (JSON/YAML) it is effectively a no-op.
+    """
+    cond = html.unescape(cond)
+    return _COND_PATTERN.sub(lambda match: _COND_REPLACEMENTS[match.group(0)], cond)
+
+
+def _resolvable_model_attr(name: str, model) -> bool:
+    """The secure boundary for resolving a bare name off the model.
+
+    Engine-protected names (``machine``, ``event``, system variables, …) and any
+    private/dunder name (leading underscore) never resolve off the model, mirroring the
+    dotted-access guard in :func:`statemachine.spec_parser.build_attribute`. System
+    variables stay reachable because they are provided via the call kwargs, which are
+    consulted before this. This keeps a semi-trusted document from reading the model's
+    internals (``_secret``) or walking the object graph (``__class__``).
+    """
+    return name not in protected_attrs and not name.startswith("_") and hasattr(model, name)
+
+
+def variable_hook(name: str) -> Callable:
+    """Resolve a datamodel name at call time.
+
+    Looks the name up in the call kwargs first (engine-provided variables such as
+    ``_event``, ``_name``, ``machine``), then falls back to a (non-protected, non-private)
+    attribute of ``machine.model``. Mirrors the namespace built by :func:`_eval`.
+    """
+
+    def resolver(*args, **kwargs):
+        if name in kwargs:
+            return kwargs[name]
+        model = kwargs["machine"].model
+        if _resolvable_model_attr(name, model):
+            return getattr(model, name)
+        raise NameError(f"name '{name}' is not defined")
+
+    resolver.__name__ = name
+    return resolver
+
+
+def cond_variable_hook(name: str) -> Callable:
+    """Resolve a name inside a guard, following the Python guard dialect.
+
+    Same lookup as :func:`variable_hook`, but a referenced **method** is *called*
+    (with dependency injection), while a property or plain attribute is *read*.
+    This keeps native ``cond``/``unless`` at parity with class-defined guards (see
+    ``docs/guards.md``): a name can be a property, an attribute or a method.
+    """
+
+    def resolver(*args, **kwargs):
+        if name in kwargs:
+            return kwargs[name]
+        model = kwargs["machine"].model
+        if _resolvable_model_attr(name, model):
+            value = getattr(model, name)
+            if callable(value):
+                return callable_method(value)(*args, **kwargs)
+            return value
+        raise NameError(f"name '{name}' is not defined")
+
+    resolver.__name__ = name
+    return resolver
+
+
+def _eval(expr: str, **kwargs) -> Any:
+    """Evaluate an expression as arbitrary Python (``trusted=True`` path only).
+
+    .. warning::
+
+        Calls the built-in :func:`eval` with no sandboxing. Only reachable when
+        the document is loaded with ``trusted=True``.
+    """
+    if "machine" in kwargs:
+        kwargs.update(
+            **{
+                k: v
+                for k, v in kwargs["machine"].model.__dict__.items()
+                if k not in protected_attrs
+            }
+        )
+        kwargs["In"] = InState(kwargs["machine"])
+    return eval(expr, {}, kwargs)
+
+
+class Evaluator(Protocol):
+    """Port: turns expression/script strings into callables.
+
+    This is the contract consumers (the processors, action compilers) depend on. They
+    never name a concrete implementation; wiring goes through :func:`evaluator_for`.
+    """
+
+    def compile_value(self, expr: str) -> Callable:  # pragma: no cover - structural Protocol
+        """Compile a value expression (``<assign>``, ``<send>``, ``<data>``, ...)."""
+        ...
+
+    def compile_bool(self, expr: str) -> Callable:  # pragma: no cover - structural Protocol
+        """Compile a boolean guard expression (``cond``)."""
+        ...
+
+    def compile_script(self, content: str) -> Callable:  # pragma: no cover - structural Protocol
+        """Compile a ``<script>`` body into a callable side effect."""
+        ...
+
+    def eval_literal(self, content: str) -> Any:  # pragma: no cover - structural Protocol
+        """Evaluate inline ``<content>`` as a literal, falling back to the raw string."""
+        ...
+
+
+class RestrictedEvaluator:
+    """Secure default: AST-whitelist evaluation, no ``eval``/``exec``.
+
+    ``<script>`` and any expression outside the supported subset (method calls,
+    dunder attribute access, lambdas, comprehensions, ...) are rejected at
+    compile time with :class:`~statemachine.exceptions.InvalidDefinition`.
+    """
+
+    def compile_value(self, expr: str) -> Callable:
+        return self._compile(expr, variable_hook)
+
+    def compile_bool(self, expr: str) -> Callable:
+        # Guards resolve names with the Python dialect (methods are called); the
+        # result is coerced to bool, awaiting it first when a coroutine (an async
+        # guard method) flows through, so the async engine works too.
+        value_fn = self._compile(normalize_cond(expr), cond_variable_hook)
+
+        def cond(*args, **kwargs):
+            result = value_fn(*args, **kwargs)
+            if isawaitable(result):
+
+                async def _coerce():
+                    return bool(await result)
+
+                return _coerce()
+            return bool(result)
+
+        return cond
+
+    def compile_script(self, content: str) -> Callable:
+        raise InvalidDefinition(
+            "<script> executes arbitrary code and is disabled by default. Pass "
+            "trusted=True to enable it, and only for trusted sources."
+        )
+
+    def eval_literal(self, content: str) -> Any:
+        try:
+            return ast.literal_eval(content)
+        except (ValueError, SyntaxError):
+            return content
+
+    @staticmethod
+    def _compile(expr: str, hook: Callable) -> Callable:
+        try:
+            return parse_expr(expr, hook)
+        except (ValueError, SyntaxError) as exc:
+            raise InvalidDefinition(
+                f"Expression {expr!r} is not allowed by the restricted "
+                f"datamodel ({exc}). Pass trusted=True to evaluate it as "
+                f"Python, and only for trusted sources."
+            ) from exc
+
+
+class PythonEvaluator:
+    """Opt-in (``trusted=True``): evaluate expressions and scripts as Python.
+
+    Preserves the legacy ``eval``/``exec`` behavior, including error timing
+    (syntax/name errors surface at call time and become ``error.execution``).
+    """
+
+    def compile_value(self, expr: str) -> Callable:
+        def value(*args, **kwargs):
+            return _eval(expr, **kwargs)
+
+        return value
+
+    def compile_bool(self, expr: str) -> Callable:
+        # Intentionally uses ``eval`` (not ``parse_expr``): the whole point of the
+        # trusted evaluator is to accept guards the restricted AST whitelist rejects —
+        # method/function calls, builtins, etc. (e.g. SCXML conformance conds like
+        # ``_event.data.get('x') == 1`` or ``hasattr(_event, 'name')``). Routing this
+        # through ``parse_expr`` would make trusted mode no more capable than the
+        # restricted one for guards and would break those documents.
+        normalized = normalize_cond(expr)
+
+        def cond(*args, **kwargs):
+            return _eval(normalized, **kwargs)
+
+        return cond
+
+    def compile_script(self, content: str) -> Callable:
+        def script(*args, **kwargs):
+            machine = kwargs["machine"]
+            local_vars = {**machine.model.__dict__}
+            exec(content, {}, local_vars)
+            for var_name, value in local_vars.items():
+                setattr(machine.model, var_name, value)
+
+        return script
+
+    def eval_literal(self, content: str) -> Any:
+        try:
+            return eval(content, {}, {})
+        except (NameError, SyntaxError, TypeError):
+            return content
+
+
+def evaluator_for(trusted: bool = False) -> Evaluator:
+    """Return the evaluation strategy for the given trust level (the wiring point).
+
+    This is the single place that maps the public ``trusted`` flag to a concrete
+    adapter, so no other module needs to import :class:`RestrictedEvaluator` or
+    :class:`PythonEvaluator`. The default (``trusted=False``) is the secure restricted
+    evaluator, so callers that omit the argument get the safe behaviour.
+    """
+    return PythonEvaluator() if trusted else RestrictedEvaluator()

statemachine/io/interpreter.py

@@ -0,0 +1,128 @@
+"""Format-neutral runtime that turns statechart definitions into running machines.
+
+The :class:`Interpreter` is the execution-model runtime, independent of input syntax. It
+owns a :class:`~statemachine.io.builder.DefinitionBuilder` (compilation), keeps the
+registry of compiled classes (``scs``, needed for ``<invoke>``), manages per-machine
+sessions, injects the system variables (``_event``/``_sessionid``/``_name``/
+``_ioprocessors``) on every event, coordinates invoke, and instantiates the root machine.
+
+It is parameterized by two ports: a :class:`~statemachine.io.ports.FormatReader` (so invoke
+can compile children in the same format) and an
+:class:`~statemachine.io.evaluators.Evaluator` (secure by default). SCXML is just one
+reader; YAML/JSON get the very same runtime behavior.
+"""
+
+import os
+from typing import Any
+
+from ..exceptions import InvalidDefinition
+from ..statemachine import StateChart
+from .builder import DefinitionBuilder
+from .class_factory import create_machine_class_from_definition
+from .evaluators import Evaluator
+from .invoke import Invoker
+from .model import InvokeDefinition
+from .model import StateMachineDefinition
+from .system_variables import IOProcessor
+from .system_variables import SessionData
+from .system_variables import build_system_variables
+from .system_variables import create_invoke_init_callable
+
+
+class Interpreter:
+    """Runtime that compiles and hosts statecharts from any format.
+
+    Args:
+        reader: the format reader, used to compile invoked children in the same format.
+        evaluator: the evaluation strategy for guards and executable content.
+    """
+
+    def __init__(self, *, reader, evaluator: Evaluator):
+        self.reader = reader
+        self._evaluator = evaluator
+        self._builder = DefinitionBuilder(evaluator=evaluator, hooks=self)
+        self.scs: "dict[str, type[StateChart]]" = {}
+        self.sessions: dict[str, SessionData] = {}
+
+    def process_definition(
+        self, definition: StateMachineDefinition, location: str, is_invoked: bool = False
+    ):
+        kwargs = self._builder.build_class_kwargs(definition, is_invoked=is_invoked)
+        self._add(location, kwargs)
+
+    def start(self, **kwargs):
+        self.root_cls = next(iter(self.scs.values()))
+        self.root = self.root_cls(**kwargs)
+        return self.root
+
+    # -- RuntimeHooks (called back by the DefinitionBuilder) -----------------------
+
+    def initial_enter_prefix(self, is_invoked: bool) -> list:
+        # Invoked children store _invoke_session/_invoke_params before any other callback.
+        if is_invoked:
+            return [create_invoke_init_callable()]
+        return []
+
+    def definition_kwargs(self, definition) -> "dict[str, Any]":
+        """Extra keyword arguments passed to ``create_machine_class_from_definition``.
+
+        The three structural ``validate_*`` checks are turned **off** for loaded
+        statecharts: declarative documents legitimately express configurations these
+        checks would reject (states reached only through parallel regions or eventless
+        paths, intentional trap/error states). The trade-off is that genuine structural
+        inconsistencies are not caught at load time; see the validations reference and
+        ``docs/io``. ``prepare_event`` injects the system variables for every format.
+        """
+        return {
+            "validate_disconnected_states": False,
+            "validate_trap_states": False,
+            "validate_final_reachability": False,
+            "start_configuration_values": list(definition.initial_states),
+            "prepare_event": self._prepare_event,
+        }
+
+    def make_invoker(self, invoke_def: InvokeDefinition) -> Invoker:
+        return Invoker(
+            definition=invoke_def,
+            base_dir=os.getcwd(),
+            register_child=self._register_child,
+            evaluator=self._evaluator,
+        )
+
+    # -- Runtime services ----------------------------------------------------------
+
+    def _prepare_event(self, *args, event, **kwargs):
+        machine = kwargs["machine"]
+        session_data = self._get_session(machine)
+        return build_system_variables(machine, session_data, event, kwargs["event_data"])
+
+    def _get_session(self, machine) -> SessionData:
+        if machine.name not in self.sessions:
+            self.sessions[machine.name] = SessionData(
+                processor=IOProcessor(self, machine=machine), machine=machine
+            )
+        return self.sessions[machine.name]
+
+    def _register_child(self, content, child_name: str) -> type:
+        """Compile and register a child statechart.
+
+        ``content`` is either source text (parsed via this interpreter's reader, so the
+        child is in the same format) or an already-parsed
+        :class:`~statemachine.io.model.StateMachineDefinition` (native inline child).
+        """
+        if isinstance(content, StateMachineDefinition):
+            definition = content
+        else:
+            definition = self.reader.read(content)
+        self.process_definition(definition, location=child_name, is_invoked=True)
+        return self.scs[child_name]
+
+    def _add(self, location: str, definition: dict[str, Any]):
+        try:
+            sc_class = create_machine_class_from_definition(location, **definition)
+            self.scs[location] = sc_class
+            return sc_class
+        except Exception as e:  # pragma: no cover
+            raise InvalidDefinition(
+                f"Failed to create state machine class: {e} from definition: {definition}"
+            ) from e

statemachine/io/{scxml/invoke.py → invoke.py}

@@ -1,27 +1,34 @@
-"""SCXML-specific invoke handler.
+"""Format-neutral invoke handler.
 
-Implements the IInvoke protocol by resolving child SCXML content (inline or
-via src/srcexpr), evaluating params/namelist in the parent context, and managing
-the child machine lifecycle including ``#_parent`` routing, autoforward, and
-finalize.
+Implements the engine's ``IInvoke`` protocol: resolves a child statechart (inline
+content, ``src`` file, or ``srcexpr``), evaluates ``params``/``namelist`` in the parent
+context, and manages the child machine lifecycle including ``#_parent`` routing,
+autoforward and finalize.
+
+The child is compiled via the ``register_child`` callback (which the interpreter wires to
+its own format reader), so invoke is not tied to SCXML: a child may be authored in any
+format the interpreter understands.
 """
 
 import asyncio
 import logging
+from collections.abc import Callable
 from inspect import isawaitable
 from pathlib import Path
 from typing import Any
-from typing import Callable
 
-from ...invoke import IInvoke
-from ...invoke import InvokeContext
+from ..invoke import IInvoke
+from ..invoke import InvokeContext
 from .actions import ExecuteBlock
-from .actions import _eval
-from .schema import InvokeDefinition
+from .evaluators import Evaluator
+from .model import InvokeDefinition
+from .model import StateMachineDefinition
+from .system_variables import EventDataWrapper
 
 logger = logging.getLogger(__name__)
 
-_VALID_INVOKE_TYPES = {
+#: Invoke ``type`` values understood by the runtime (SCXML processor URLs + ``None``).
+VALID_INVOKE_TYPES = {
     None,
     "scxml",
     "http://www.w3.org/TR/scxml",
@@ -30,10 +37,10 @@ _VALID_INVOKE_TYPES = {
 }
 
 
-class SCXMLInvoker:
-    """SCXML-specific invoke handler implementing the IInvoke protocol.
+class Invoker:
+    """Invoke handler implementing the IInvoke protocol.
 
-    Resolves the child SCXML from inline content, src file, or srcexpr,
+    Resolves the child statechart from inline content, a ``src`` file or ``srcexpr``,
     evaluates params/namelist, and manages the child machine lifecycle.
     """
 
@@ -41,12 +48,14 @@ class SCXMLInvoker:
         self,
         definition: InvokeDefinition,
         base_dir: str,
-        register_child: "Callable[[str, str], type]",
+        register_child: "Callable[[StateMachineDefinition | str, str], type]",
+        evaluator: Evaluator,
     ):
         self._definition = definition
         self._register_child = register_child
         self._child: Any = None
         self._base_dir: str = base_dir
+        self._evaluator: Evaluator = evaluator
 
         # Duck-typed attributes for InvokeManager
         self.invoke_id: "str | None" = definition.id
@@ -56,7 +65,10 @@ class SCXMLInvoker:
         # Pre-compile finalize block
         self._finalize_block: "ExecuteBlock | None" = None
         if definition.finalize and not definition.finalize.is_empty:
-            self._finalize_block = ExecuteBlock(definition.finalize)
+            self._finalize_block = ExecuteBlock(definition.finalize, self._evaluator)
+
+    def _eval(self, expr: str, machine) -> Any:
+        return self._evaluator.compile_value(expr)(machine=machine)
 
     def run(self, ctx: InvokeContext) -> Any:
         """Create and run the child state machine."""
@@ -69,27 +81,27 @@ class SCXMLInvoker:
         # Resolve invoke type
         invoke_type = self._definition.type
         if self._definition.typeexpr:
-            invoke_type = _eval(self._definition.typeexpr, machine=machine)
+            invoke_type = self._eval(self._definition.typeexpr, machine=machine)
 
-        if invoke_type not in _VALID_INVOKE_TYPES:
+        if invoke_type not in VALID_INVOKE_TYPES:
             raise ValueError(
-                f"Unsupported invoke type: {invoke_type}. Supported types: {_VALID_INVOKE_TYPES}"
+                f"Unsupported invoke type: {invoke_type}. Supported types: {VALID_INVOKE_TYPES}"
             )
 
-        # Resolve child SCXML content
-        scxml_content = self._resolve_content(machine)
-        if scxml_content is None:
+        # Resolve child statechart content
+        child_content = self._resolve_content(machine)
+        if child_content is None:
             raise ValueError("No content resolved for <invoke>")
 
         # Evaluate params and namelist
         invoke_params = self._evaluate_params(machine)
 
         # Parse and create the child machine
-        child_cls = self._create_child_class(scxml_content, ctx.invokeid)
+        child_cls = self._create_child_class(child_content, ctx.invokeid)
 
         # _invoke_session and _invoke_params are passed as kwargs so that the
         # invoke_init callback (inserted at position 0 in the initial state's onentry
-        # by the processor) can pop them and store them on the machine instance.
+        # by the interpreter) can pop them and store them on the machine instance.
         #
         # The _ChildRefSetter listener captures ``self._child`` during the first
         # state entry, before the processing loop blocks.  This is necessary
@@ -108,7 +120,7 @@ class SCXMLInvoker:
 
     def on_cancel(self):
         """Cancel the child machine and all its invocations."""
-        from ...invoke import _stop_child_machine
+        from ..invoke import _stop_child_machine
 
         _stop_child_machine(self._child)
         self._child = None
@@ -129,32 +141,36 @@ class SCXMLInvoker:
                 "machine": machine,
                 "model": machine.model,
             }
-            # Inject SCXML context variables
-            from .actions import EventDataWrapper
-
             kwargs.update(
                 {k: v for k, v in machine.model.__dict__.items() if not k.startswith("_")}
             )
-            # Build EventDataWrapper from trigger_data's kwargs
             kwargs["_event"] = EventDataWrapper.from_trigger_data(trigger_data)
             self._finalize_block(**kwargs)
 
-    def _resolve_content(self, machine) -> "str | None":
-        """Resolve the child SCXML content from content/src/srcexpr."""
+    def _resolve_content(self, machine):
+        """Resolve the child statechart content from content/src/srcexpr.
+
+        Returns either a source string (file text / inline document text) that the reader
+        will parse, or an already-parsed definition (native inline child), which the
+        interpreter registers directly.
+        """
         defn = self._definition
 
-        if defn.content:
-            # Content could be an expr to evaluate or inline SCXML
-            if defn.content.lstrip().startswith("<"):
-                return defn.content
+        if defn.content is not None:
+            content = defn.content
+            if not isinstance(content, str):
+                # Native inline child: an already-parsed StateMachineDefinition.
+                return content
+            if self._is_inline_document(content):
+                return content
             # It's an expression — evaluate it
-            result = _eval(defn.content, machine=machine)
+            result = self._eval(content, machine=machine)
             if isinstance(result, str):
                 return result
             return str(result)
 
         if defn.srcexpr:
-            src = _eval(defn.srcexpr, machine=machine)
+            src = self._eval(defn.srcexpr, machine=machine)
         elif defn.src:
             src = defn.src
         else:
@@ -166,12 +182,20 @@ class SCXMLInvoker:
         else:
             path = Path(src)
 
-        # Resolve relative to the base directory of the parent SCXML file
+        # Resolve relative to the base directory of the parent document
         if not path.is_absolute():
             path = Path(self._base_dir) / path
 
         return path.read_text()
 
+    @staticmethod
+    def _is_inline_document(content: str) -> bool:
+        """Whether ``content`` is an inline document (vs an expression to evaluate).
+
+        The default heuristic recognizes inline XML (SCXML). Other formats may override.
+        """
+        return content.lstrip().startswith("<")
+
     def _evaluate_params(self, machine) -> dict:
         """Evaluate params and namelist into a dict of values."""
         defn = self._definition
@@ -186,28 +210,28 @@ class SCXMLInvoker:
         # Evaluate param elements
         for param in defn.params:
             if param.expr is not None:
-                result[param.name] = _eval(param.expr, machine=machine)
+                result[param.name] = self._eval(param.expr, machine=machine)
             elif param.location is not None:
-                result[param.name] = _eval(param.location, machine=machine)
+                result[param.name] = self._eval(param.location, machine=machine)
 
         return result
 
-    def _create_child_class(self, scxml_content: str, invokeid: str):
-        """Parse the child SCXML and create a machine class."""
+    def _create_child_class(self, content: "StateMachineDefinition | str", invokeid: str):
+        """Compile the child statechart and create a machine class."""
         child_name = f"invoke_{invokeid}"
-        return self._register_child(scxml_content, child_name)
+        return self._register_child(content, child_name)
 
 
 class _ChildRefSetter:
     """Listener that captures the child machine reference during initialization.
 
     The child's ``__init__`` blocks inside the processing loop (e.g. when there
-    are delayed events).  By using this listener, ``SCXMLInvoker._child`` is set
-    during the first state entry — *before* the processing loop starts spinning —
-    so that ``on_event()`` can forward events to the child immediately.
+    are delayed events).  By using this listener, ``Invoker._child`` is set during
+    the first state entry — *before* the processing loop starts spinning — so that
+    ``on_event()`` can forward events to the child immediately.
     """
 
-    def __init__(self, invoker: "SCXMLInvoker"):
+    def __init__(self, invoker: "Invoker"):
         self._invoker = invoker
 
     def on_enter_state(self, machine=None, **kwargs):
@@ -221,13 +245,17 @@ class _InvokeSession:
     def __init__(self, parent, invokeid: str):
         self.parent = parent
         self.invokeid = invokeid
+        self._pending_tasks: "set[asyncio.Future]" = set()
+        """Strong refs to scheduled sends; the loop only holds weak refs to tasks."""
 
     def send_to_parent(self, event: str, **data):
         """Send an event to the parent machine's external queue."""
         result = self.parent.send(event, _invokeid=self.invokeid, **data)
         if isawaitable(result):
-            asyncio.ensure_future(result)
+            task = asyncio.ensure_future(result)
+            self._pending_tasks.add(task)
+            task.add_done_callback(self._pending_tasks.discard)
 
 
 # Verify protocol compliance at import time
-assert isinstance(SCXMLInvoker.__new__(SCXMLInvoker), IInvoke)
+assert isinstance(Invoker.__new__(Invoker), IInvoke)

statemachine/io/json/__init__.py

@@ -0,0 +1 @@
+"""JSON statechart format adapter."""