refactor: rename error_on_execution to catch_errors_as_events (#583)

Closes #581

The old name read as "error on execution" (describing a problem) rather
than conveying the behavior it controls. The new name says exactly what
it does: catch errors and dispatch them as `error.execution` events.

Renamed across source code, engine, SCXML actions, all tests, all docs,
and AGENTS.md.

Author: fgmacedo

AGENTS.md

@@ -41,9 +41,9 @@ The engine follows the SCXML run-to-completion (RTC) model with two processing l
 - `send()` → **external queue** (processed after current macrostep ends).
 - `raise_()` → **internal queue** (processed within the current macrostep, before external events).
 
-### Error handling (`error_on_execution`)
+### Error handling (`catch_errors_as_events`)
 
-- `StateChart` has `error_on_execution=True` by default; `StateMachine` has `False`.
+- `StateChart` has `catch_errors_as_events=True` by default; `StateMachine` has `False`.
 - Errors are caught at the **block level** (per onentry/onexit/transition `on` block), not per
   microstep. This means `after` callbacks still run even when an action raises — making
   `after_<event>()` a natural **finalize** hook (runs on both success and failure paths).

docs/actions.md

@@ -69,7 +69,7 @@ The `state` column shows what the `state` parameter resolves to when
 
 ```{tip}
 `after` callbacks run even when an earlier group raises and
-`error_on_execution` is enabled — making them a natural **finalize** hook.
+`catch_errors_as_events` is enabled — making them a natural **finalize** hook.
 See {ref}`error-handling-cleanup-finalize` for the full pattern.
 ```
 

docs/async.md

@@ -161,7 +161,7 @@ processing loop. Events triggered from within callbacks (via `send()` or
 are enqueued and processed within the current macrostep.
 ```
 
-If an exception occurs during processing (with `error_on_execution=False`),
+If an exception occurs during processing (with `catch_errors_as_events=False`),
 the exception is routed to the caller whose event caused it. Other callers
 whose events were still pending will also receive the exception, since the
 processing loop clears the queue on failure.

docs/behaviour.md

@@ -33,7 +33,7 @@ SCXML-compliant behavior provides more predictable semantics.
 | `allow_event_without_transition` | `True` | `False` | Tolerate events that don't match any transition |
 | `enable_self_transition_entries` | `True` | `False` | Execute entry/exit actions on self-transitions |
 | `atomic_configuration_update` | `False` | `True` | When to update {ref}`configuration <querying-configuration>` during a microstep |
-| `error_on_execution` | `True` | `False` | Catch action errors as `error.execution` events |
+| `catch_errors_as_events` | `True` | `False` | Catch action errors as `error.execution` events |
 
 Each attribute is described below, with cross-references to the pages that
 cover the topic in depth.
@@ -142,7 +142,7 @@ in callbacks.
 ```
 
 
-## `error_on_execution`
+## `catch_errors_as_events`
 
 When `True` (SCXML default), runtime exceptions in action callbacks
 (entry/exit, transition `on`) are caught by the engine and dispatched as
@@ -152,7 +152,7 @@ propagate normally to the caller.
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the
-`error_on_execution` setting. See {ref}`validators` for details.
+`catch_errors_as_events` setting. See {ref}`validators` for details.
 ```
 
 ```{seealso}
@@ -168,7 +168,7 @@ adopt SCXML semantics incrementally in an existing `StateMachine`:
 
 ```python
 class MyMachine(StateMachine):
-    error_on_execution = True
+    catch_errors_as_events = True
     # ... everything else behaves as before ...
 ```
 

docs/error_handling.md

@@ -15,7 +15,7 @@ failures by transitioning to an error state, retrying, or recovering. This
 follows the [SCXML error handling specification](https://www.w3.org/TR/scxml/#errorsAndEvents).
 
 ```{tip}
-`error_on_execution` is a class attribute that controls this behavior.
+`catch_errors_as_events` is a class attribute that controls this behavior.
 `StateChart` uses `True` by default (SCXML-compliant); set it to `False`
 to let exceptions propagate to the caller instead. See {ref}`behaviour`
 for the full comparison of behavioral attributes and how to customize them.
@@ -226,7 +226,7 @@ more detailed version of this pattern with annotated output.
 {ref}`Validators <validators>` operate in the **transition-selection** phase,
 before any state changes occur. Their exceptions **always propagate** to the
 caller — they are never caught by the engine and never converted to
-`error.execution` events, regardless of the `error_on_execution` setting.
+`error.execution` events, regardless of the `catch_errors_as_events` setting.
 
 This is intentional: a validator rejection means the transition should not
 happen at all. It is semantically equivalent to a condition returning
@@ -240,7 +240,7 @@ propagation.
 
 ```{seealso}
 See {ref}`behaviour` for the full comparison of behavioral attributes
-and how to customize `error_on_execution` and other settings.
+and how to customize `catch_errors_as_events` and other settings.
 See {ref}`actions` for the callback execution order within each
 microstep.
 ```

docs/events.md

@@ -305,7 +305,7 @@ on a non-final state raises `InvalidDefinition`.
 ### `error.execution` events
 
 When a callback raises during a macrostep and
-{ref}`error_on_execution <behaviour>` is enabled, the engine dispatches an
+{ref}`catch_errors_as_events <behaviour>` is enabled, the engine dispatches an
 `error.execution` internal event. Define a transition for this event to
 recover from errors within the statechart:
 

docs/guards.md

@@ -293,13 +293,13 @@ True
 ### Validators always propagate
 
 Validator exceptions **always propagate** to the caller, regardless of the
-`error_on_execution` flag. This is intentional: validators operate in the
+`catch_errors_as_events` flag. This is intentional: validators operate in the
 **transition-selection** phase, not the execution phase. A validator that
 rejects is semantically equivalent to a condition that returns `False` —
 the transition simply should not happen. The difference is that the
 validator communicates the reason via an exception.
 
-This means that even when `error_on_execution = True` (the default for
+This means that even when `catch_errors_as_events = True` (the default for
 `StateChart`):
 
 - Validator exceptions are **not** converted to `error.execution` events.

docs/invoke.md

@@ -343,7 +343,7 @@ True
 ## Error handling
 
 If an invoke handler raises an exception, `error.execution` is sent to the machine's
-internal queue (when `error_on_execution=True`, the default for `StateChart`). You can
+internal queue (when `catch_errors_as_events=True`, the default for `StateChart`). You can
 handle it with a transition for `error.execution`:
 
 ```py

docs/processing_model.md

@@ -47,7 +47,7 @@ callback groups defined in the {ref}`execution order <actions>`:
 8. **After** — run post-transition callbacks (always runs, even on error).
 
 ```{tip}
-If an error occurs during steps 3–6 and `error_on_execution` is enabled,
+If an error occurs during steps 3–6 and `catch_errors_as_events` is enabled,
 the error is caught at the **block level** — remaining actions in that block
 are skipped, but the microstep continues. See
 {ref}`error-execution` and the

docs/releases/3.0.0.md

@@ -293,7 +293,7 @@ Existing calls to `send()` are fully backward compatible.
 
 ### Error handling with `error.execution`
 
-When `error_on_execution` is enabled (default in `StateChart`), runtime exceptions during
+When `catch_errors_as_events` is enabled (default in `StateChart`), runtime exceptions during
 transitions are caught and result in an internal `error.execution` event. This follows
 the [SCXML error handling specification](https://www.w3.org/TR/scxml/#errorsAndEvents).
 
@@ -458,7 +458,7 @@ machines can receive context at creation time:
 #### `StateChart` base class
 
 The new `StateChart` class is the recommended base for all new state machines. It enables
-SCXML-compliant defaults: `error_on_execution`, `enable_self_transition_entries`, and
+SCXML-compliant defaults: `catch_errors_as_events`, `enable_self_transition_entries`, and
 non-atomic configuration updates. The existing `StateMachine` class is now a subclass with
 backward-compatible defaults. See {ref}`behaviour` for a comparison table.