# Mission: Statecharts

## Why
Martin wants to reach for a statechart the way one reaches for a data structure: recognise
the shape of a problem that wants one, draw it, and then transcribe the drawing into working
code — in Python, with `python-statemachine`, but the drawing is the part that transfers.
The target is the modelling, not the library: being able to say *why* a box goes inside
another box, *what* belongs in a region and what belongs in context, and *where* a feature's
scope ends.

## Success looks like
- Can spot **state explosion** in existing code — a pile of booleans, a `status` enum with
  impossible combinations, an `if` that checks three flags — and say which statechart
  construct collapses it.
- Can decide, for any given fact about a system, whether it is a **state**, a **region**, or
  **context** — and defend the choice. (The rule of thumb being tested: if it has an
  unbounded or arithmetic range, it is context.)
- Can place a transition correctly in a hierarchy: knows what the **transition domain** is,
  which states get exited and entered in what order, and why a transition on a parent is
  cheaper than the same transition drawn n times on its children.
- Can use **history** deliberately — knows the difference between shallow and deep, knows
  that history is not the same as context, and knows when to clear it.
- Can read a **parallel** decomposition critically: tell a genuine orthogonal region from
  two regions that secretly constrain each other, and express the real constraint as a guard
  rather than as a product of states.
- Can take an existing **flat** machine (RFC 9293's TCP diagram is the worked case) and
  refactor it into a hierarchy without changing behaviour, with a test suite proving it.
- Can explain the **run-to-completion** model well enough to predict what happens when an
  action sends an event, and why eventless transitions fire before queued ones.
- Retains the canonical vocabulary — configuration, compound, orthogonal region,
  pseudo-state, guard, internal transition, macrostep — well enough to argue from the
  literature rather than from taste.

## Constraints
- Implementation in **Python**, with `python-statemachine` 3.2.x (the `StateChart` base
  class, SCXML semantics). Other libraries appear only as contrast.
- Every practice problem must be **runnable and self-checking**: a spec, a skeleton, and an
  acceptance test suite that goes green or does not.
- Diagrams before code, in every problem. Mermaid is the drawing notation.
- Prescription only where it is attributable — Harel, the SCXML specification, the UML
  specification, or an RFC. Where a library deviates from the spec, say so and cite the
  observed behaviour.

## Out of scope
- Formal verification of statecharts (model checking, temporal logic specification).
- Code generation from models, and the tools around it (STATEMATE, Rhapsody, Yakindu).
- The statechart-variant semantics literature — twenty-odd dialects differing on
  simultaneity and broadcast. One semantics (SCXML's) is enough to learn on.
- Actor systems and workflow engines as alternative ways to model long-lived state.