feat: invoke callback group — spawn external work from states (#571)

* feat: invoke callback group — spawn external work from states

Add invoke as a first-class callback group (CallbackGroup.INVOKE), following
SCXML <invoke> semantics. States can spawn background work (API calls, file I/O,
child state machines) on entry and cancel it on exit.

- New CallbackGroup.INVOKE with convention naming (on_invoke_<state>),
  decorator (@state.invoke), and inline callables
- IInvoke protocol for advanced handlers with InvokeContext (cancellation,
  send events to parent, machine reference)
- StateChartInvoker adapter for child state machine invocation
- invoke_group() for running multiple callables concurrently and waiting
  for all results as a single done.invoke event
- InvokeManager lifecycle management integrated into both sync and async engines
  (sync: daemon threads, async: thread executor wrapped in asyncio.Task)
- done_invoke_<state> factory prefix maps to done.invoke.<state> event family
- visitor pattern (visit/async_visit) on CallbacksExecutor and CallbacksRegistry
- __contains__ on CallbacksRegistry to avoid direct _registry access
- Full test suite and documentation with practical file I/O examples
- Plain callables receive kwargs via SignatureAdapter dependency injection
- IInvoke handlers receive kwargs via ctx.kwargs

This allows patterns like sm.send("start", file_name="config.json")
where the invoke handler reads file_name as a parameter.

Author: fgmacedo

.pre-commit-config.yaml

@@ -33,7 +33,7 @@ repos:
     pass_filenames: false
   - id: pytest
     name: Pytest
-    entry: uv run pytest -n auto
+    entry: uv run pytest -n auto --cov-fail-under=100
     types: [python]
     language: system
     pass_filenames: false

docs/index.md

@@ -19,6 +19,7 @@ integrations
 diagram
 weighted_transitions
 processing_model
+invoke
 statecharts
 api
 auto_examples/index