fix: make disconnected states validation hierarchy-aware (#573)

The `visit_connected_states` BFS now traverses the state hierarchy:
entering a compound/parallel state implicitly enters its initial
children, and being in a child implies being in all ancestor states.

This removes the need for `validate_disconnected_states = False` in
virtually all parallel, compound, and history state examples — the
flag was only needed because the validator didn't understand
hierarchical entry semantics.

Author: fgmacedo

README.md

@@ -181,7 +181,6 @@ regions reach a final state:
 >>> from statemachine import StateChart, State
 
 >>> class DeployPipeline(StateChart):
-...     validate_disconnected_states = False
 ...     class deploy(State.Parallel):
 ...         class build(State.Compound):
 ...             compiling = State(initial=True)
@@ -219,7 +218,6 @@ of starting from the initial one:
 >>> from statemachine import HistoryState, StateChart, State
 
 >>> class EditorWithHistory(StateChart):
-...     validate_disconnected_states = False
 ...     class editor(State.Compound):
 ...         source = State(initial=True)
 ...         visual = State()

docs/releases/3.0.0.md

@@ -127,7 +127,6 @@ the parent and all descendants. See {ref}`statecharts` for full details.
 >>> from statemachine import State, StateChart
 
 >>> class WarOfTheRing(StateChart):
-...     validate_disconnected_states = False
 ...     class war(State.Parallel):
 ...         class frodos_quest(State.Compound):
 ...             shire = State(initial=True)
@@ -160,7 +159,6 @@ Supports both shallow (`HistoryState()`) and deep (`HistoryState(deep=True)`) hi
 >>> from statemachine import HistoryState, State, StateChart
 
 >>> class GollumPersonality(StateChart):
-...     validate_disconnected_states = False
 ...     class personality(State.Compound):
 ...         smeagol = State(initial=True)
 ...         gollum = State()
@@ -402,15 +400,6 @@ if sm.is_terminated:
     print("State machine has finished.")
 ```
 
-
-### Disable single graph component validation
-
-Since SCXML don't require that all states should be reachable by transitions, we added a class-level
-flag `validate_disconnected_states: bool = True` that can be used to disable this validation.
-
-It's already disabled when parsing SCXML files.
-
-
 ### Typed models with `Generic[TModel]`
 
 `StateChart` now supports a generic type parameter for the model, enabling full type

docs/statecharts.md

@@ -339,7 +339,6 @@ independently — events in one region don't affect others. Use `State.Parallel`
 >>> from statemachine import State, StateChart
 
 >>> class WarOfTheRing(StateChart):
-...     validate_disconnected_states = False
 ...     class war(State.Parallel):
 ...         class frodos_quest(State.Compound):
 ...             shire = State(initial=True)
@@ -373,7 +372,6 @@ state have reached a final state:
 >>> from statemachine import State, StateChart
 
 >>> class WarWithDone(StateChart):
-...     validate_disconnected_states = False
 ...     class war(State.Parallel):
 ...         class quest(State.Compound):
 ...             start_q = State(initial=True)
@@ -396,12 +394,6 @@ True
 True
 
 ```
-
-```{note}
-Parallel states commonly require `validate_disconnected_states = False` because
-regions may not be reachable from each other via transitions.
-```
-
 (history-states)=
 ## History pseudo-states
 
@@ -415,7 +407,6 @@ Import `HistoryState` and place it inside a `State.Compound`:
 >>> from statemachine import HistoryState, State, StateChart
 
 >>> class GollumPersonality(StateChart):
-...     validate_disconnected_states = False
 ...     class personality(State.Compound):
 ...         smeagol = State(initial=True)
 ...         gollum = State()
@@ -454,7 +445,6 @@ state and restores the full hierarchy:
 >>> from statemachine import HistoryState, State, StateChart
 
 >>> class DeepMemoryOfMoria(StateChart):
-...     validate_disconnected_states = False
 ...     class moria(State.Compound):
 ...         class halls(State.Compound):
 ...             entrance = State(initial=True)
@@ -677,7 +667,6 @@ currently active. This is especially useful for cross-region guards in parallel
 >>> from statemachine import State, StateChart
 
 >>> class CoordinatedAdvance(StateChart):
-...     validate_disconnected_states = False
 ...     class forces(State.Parallel):
 ...         class vanguard(State.Compound):
 ...             waiting = State(initial=True)

docs/states.md

@@ -233,7 +233,6 @@ independently. Define them using `State.Parallel`:
 >>> from statemachine import State, StateChart
 
 >>> class WarOfTheRing(StateChart):
-...     validate_disconnected_states = False
 ...     class war(State.Parallel):
 ...         class quest(State.Compound):
 ...             start = State(initial=True)
@@ -267,7 +266,6 @@ Re-entering via the history state restores the previously active child. Import a
 >>> from statemachine import HistoryState, State, StateChart
 
 >>> class WithHistory(StateChart):
-...     validate_disconnected_states = False
 ...     class mode(State.Compound):
 ...         a = State(initial=True)
 ...         b = State()

docs/transitions.md

@@ -486,7 +486,6 @@ source and all target states.
 >>> from statemachine import State, StateChart
 
 >>> class MiddleEarthJourney(StateChart):
-...     validate_disconnected_states = False
 ...     class rivendell(State.Compound):
 ...         council = State(initial=True)
 ...         preparing = State()

statemachine/graph.py

@@ -18,6 +18,16 @@ def visit_connected_states(state: "State"):
         already_visited.add(state)
         yield state
         visit.extend(t.target for t in state.transitions if t.target)
+        # Traverse the state hierarchy: entering a compound/parallel state
+        # implicitly enters its initial children (all children for parallel).
+        for child in state.states:
+            if child.initial:
+                visit.append(child)
+        for child in state.history:
+            visit.append(child)
+        # Being in a child state implies being in all ancestor states.
+        if state.parent:
+            visit.append(state.parent)
 
 
 def disconnected_states(starting_state: "State", all_states: MutableSet["State"]):

statemachine/io/__init__.py

@@ -156,7 +156,7 @@ def create_machine_class_from_definition(
             ``history``, and transitions via ``on`` (event-triggered) or
             ``transitions`` (eventless).
         **definition: Additional keyword arguments passed to the metaclass
-            (e.g., ``validate_disconnected_states=False``).
+            (e.g., ``validate_final_reachability=False``).
 
     Returns:
         A new StateChart subclass configured with the given states and transitions.

tests/examples/statechart_compound_machine.py

@@ -22,8 +22,6 @@ class QuestMachine(StateChart):
     and ``rivendell`` (with council activities). A ``wilderness`` state connects them.
     """
 
-    validate_disconnected_states = False
-
     class shire(State.Compound):
         bag_end = State("Bag End", initial=True)
         green_dragon = State("The Green Dragon")

tests/examples/statechart_history_machine.py

@@ -25,8 +25,6 @@ class PersonalityMachine(StateChart):
     pseudo-state, the previously active personality is restored.
     """
 
-    validate_disconnected_states = False
-
     class personality(State.Compound):
         smeagol = State("Smeagol", initial=True)
         gollum = State("Gollum")
@@ -89,8 +87,6 @@ class personality(State.Compound):
 class DeepPersonalityMachine(StateChart):
     """A machine with nested compounds and deep history."""
 
-    validate_disconnected_states = False
-
     class realm(State.Compound):
         class inner(State.Compound):
             entrance = State("Entrance", initial=True)

tests/examples/statechart_in_condition_machine.py

@@ -23,8 +23,6 @@ class FellowshipMachine(StateChart):
     only follows Frodo to Mordor after Frodo has already arrived there.
     """
 
-    validate_disconnected_states = False
-
     class quest(State.Parallel):
         class frodo_path(State.Compound):
             shire_f = State("Frodo in Shire", initial=True)