# Statechart Resources

⭐ marks the core set — the sources the lessons actually quote.

## The primary literature

- ⭐ [Paper: "Statecharts: A Visual Formalism for Complex Systems" — David Harel,
  *Science of Computer Programming* 8(3):231–274, 1987](https://doi.org/10.1016/0167-6423(87)90035-9)
  ([scanned copy, Internet Archive](https://archive.org/details/7.-statecharts) ·
  [PDF mirror](https://web.archive.org/web/2019/http://www.inf.ed.ac.uk/teaching/courses/seoc/2005_2006/resources/statecharts.pdf))
  The source. Statecharts = state diagrams + **depth** + **orthogonality** + **broadcast
  communication**. The running example is the author's own Citizen Quartz Multi-Alarm III
  wristwatch, reverse-engineered by observation; Figure 31 is the full chart.
  Use for: the definition of the three constructs; the default-arrow and H / H\* notation;
  the `clear-history(state)` and `clear-history(state*)` actions; the argument that a
  feature's **scope** is the box you draw it in ("the test will work only when the system is
  in `time`"); Figure 25's stopwatch as two orthogonal regions; the worked scenario where one
  chord of button presses lands you "in `time`, one month ahead, with the beeper beeping and
  the light on".
- ⭐ [Paper: "Statecharts in the Making: A Personal Account" — David Harel, HOPL III, 2007](https://www.weizmann.ac.il/math/harel/sites/math.harel/files/users/user50/Statecharts.History.pdf)
  How the notation came about, at the Israel Aircraft Industries avionics project.
  Use for: why the constructs exist — the design pressures that produced them — and for
  honest retrospection about what the 1987 semantics left underspecified.
- [Book: _Modeling Reactive Systems with Statecharts: The STATEMATE Approach_ — Harel &
  Politi, McGraw-Hill 1998](https://www.weizmann.ac.il/math/harel/)
  Out of print; downloadable from the author's page. The long-form treatment: activity
  charts, module charts, and the statechart language as actually shipped.
  Use for: the vocabulary in its full form, and the distinction between a behavioural model
  and a structural one.

## The specifications

- ⭐ [W3C: State Chart XML (SCXML): State Machine Notation for Control Abstraction —
  Recommendation, 1 September 2015](https://www.w3.org/TR/scxml/)
  The executable, unambiguous semantics, and the one `python-statemachine`'s `StateChart`
  class implements. Appendix D gives the interpretation algorithm in pseudocode:
  `selectTransitions`, `computeExitSet`, the LCCA (least common compound ancestor) rule for
  the transition domain, and the macrostep/microstep loop.
  Use for: anything where "what actually happens" is in question — entry/exit ordering,
  transition selection priority, internal vs. external transitions, how history is recorded.
- [OMG: Unified Modeling Language 2.5.1, §14 "StateMachines"](https://www.omg.org/spec/UML/2.5.1/PDF)
  Use for: the UML names for the same ideas (pseudostate, region, submachine, entry/exit
  point, deferred events), which is the vocabulary most tools and most colleagues use.
- ⭐ [RFC 9293 — Transmission Control Protocol, §3.3.2 "State Machine Overview"](https://www.rfc-editor.org/rfc/rfc9293.html#section-3.3.2)
  ([RFC 793, the 1981 original](https://www.rfc-editor.org/rfc/rfc793.html))
  Figure 5 is the canonical real-world flat state diagram: eleven states, no hierarchy, and
  a standing note that it "is only a summary and must not be taken as the total
  specification". The material for P4.
  Use for: a machine that was specified flat by people who knew what they were doing, and
  what hierarchy does and does not buy when you group it afterwards.

## Practitioner sources

- ⭐ [Site: statecharts.dev — Erik Mogensen et al.](https://statecharts.dev/)
  The best plain-language glossary of the vocabulary: [compound
  state](https://statecharts.dev/glossary/compound-state.html), [parallel
  state](https://statecharts.dev/glossary/parallel-state.html), [history
  state](https://statecharts.dev/glossary/history-state.html),
  [pseudostate](https://statecharts.dev/glossary/pseudostate.html), guard, internal
  transition. Also ["What is a statechart?"](https://statecharts.dev/what-is-a-statechart.html),
  which is the clearest short statement of what the constructs buy you.
  Use for: definitions, and for the argument against the boolean-flag design they replace.
- [Docs: Stately / XState — parallel states, history states, guards](https://stately.ai/docs/parallel-states)
  A second implementation of the same semantics, with a visual editor. Useful as a
  cross-check: if a construct behaves differently in XState and in `python-statemachine`,
  one of them is deviating from SCXML.
- [Book: _Practical UML Statecharts in C/C++_ (2nd ed.) — Miro Samek](https://www.state-machine.com/psicc2)
  and [Article: "Introduction to Hierarchical State Machines" — Barr Group](https://barrgroup.com/embedded-systems/how-to/introduction-hierarchical-state-machines)
  The embedded-systems tradition. Use for: entry/exit actions as the mechanism that makes
  safety invariants structural rather than remembered, and for the "state-handler" style of
  hand-implementing hierarchy when you have no library.

## The library

- ⭐ [Docs: python-statemachine 3.2.x](https://python-statemachine.readthedocs.io/en/latest/)
  The pages that matter: [states](https://python-statemachine.readthedocs.io/en/latest/states.html)
  (`State.Compound`, `State.Parallel`, `HistoryState`),
  [transitions](https://python-statemachine.readthedocs.io/en/latest/transitions.html)
  (internal vs. self, eventless, cross-boundary, priority),
  [processing model](https://python-statemachine.readthedocs.io/en/latest/processing_model.html)
  (macrostep, microstep, the two queues), and
  [behaviour](https://python-statemachine.readthedocs.io/en/latest/behaviour.html)
  (`StateChart` vs. the legacy `StateMachine`, and the four flags that separate them).
- [Library: Sismic — Decan & Mens, *SoftwareX* 13 (2021) 100590](https://doi.org/10.1016/j.softx.2020.100590)
  ([docs](https://sismic.readthedocs.io/))
  The other serious Python option: statecharts defined in YAML, with a contract/property
  language for testing them. Use for: contrast — what a statechart library looks like when
  the model is data rather than a class.

## Gaps

- **No free, authoritative comparison of statechart variant semantics.** Roughly two dozen
  dialects disagree about simultaneity, broadcast and transition priority; the standard
  survey (von der Beeck, "A Comparison of Statecharts Variants", FTRTFT 1994) is paywalled.
  The lessons therefore teach one semantics — SCXML's — and say so rather than pretending
  it is the only one.
- **No published source on where `python-statemachine` 3.2.1 deviates from SCXML.** Three
  deviations were found by experiment while building the exercises and are recorded in
  `exercises/README.md` with reproductions. They are observed behaviour, not documented
  behaviour, and may be fixed in a later release.
- **Nothing high-trust on when *not* to use a statechart.** The practitioner sources are all
  advocacy. The heuristics in lesson 05 (unbounded range → context; independent lifetime →
  separate machine) are synthesis, and flagged as such.