Learning path

Statecharts — Status

Five lessons for the vocabulary, five problems for the judgement. Everything is runnable: 115 acceptance tests across the five problems, all green against the reference solutions. See MISSION.md and RESOURCES.md.

Knowledge graph

graph TD
  A["State explosion
why flat machines double"]
  A --> B["Configuration
not “the current state”"]

  B --> C["Depth
compound states"]
  B --> D["Orthogonality
parallel regions"]
  B --> E["Broadcast
one event, every region"]

  C --> C1["Transition domain / LCCA
which boxes get exited"]
  C --> C2["Entry & exit ordering
and invariants that follow"]
  C --> C3["Deepest-match priority
general rule, local exception"]
  C --> C4["Internal vs self transitions"]

  D --> D1["The independence test
impossible vs merely forbidden"]
  D --> D2["Cross-region guards
Harel’s in(state)"]
  D --> D3["Scope
the box is the specification"]

  C1 --> F["History
shallow H · deep H*"]
  F --> F1["History is on the arrow,
not on the box"]
  F --> F2["clear-history
when memory stops being true"]

  C --> G["Context
extended state"]
  G --> G1["Guards & guard order"]
  G1 --> G2["Eventless transitions"]
  E --> H["Run-to-completion
macrostep · microstep"]
  G2 --> H
  H --> H1["Two queues,
and the ordering trap"]

  C2 --> P1["P1 · Microwave"]
  F1 --> P2["P2 · Media player"]
  D2 --> P2
  H1 --> P3["P3 · Elevator"]
  D1 --> P3
  C3 --> P4["P4 · TCP"]
  D3 --> P5["P5 · Digital watch"]
  F2 --> P5
  P3 --> P4
  P4 --> P5

  classDef ready   fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95,stroke-dasharray:5 3;
  classDef core    fill:#dbeafe,stroke:#2563eb,color:#1e3a8a,stroke-width:2px;
  classDef problem fill:#fffbeb,stroke:#d97706,color:#78350f,stroke-width:2px;

  class A,B,C,D,E,F,G,H core;
  class C1,C2,C3,C4,D1,D2,D3,F1,F2,G1,G2,H1 ready;
  class P1,P2,P3,P4,P5 problem;

  click B "lessons/01-configuration-not-state.html" "Lesson 01"
  click A "lessons/01-configuration-not-state.html" "Lesson 01"
  click C "lessons/02-depth.html" "Lesson 02"
  click C1 "lessons/02-depth.html" "Lesson 02"
  click C2 "lessons/02-depth.html" "Lesson 02"
  click C3 "lessons/02-depth.html" "Lesson 02"
  click C4 "lessons/02-depth.html" "Lesson 02"
  click D "lessons/03-orthogonality.html" "Lesson 03"
  click D1 "lessons/03-orthogonality.html" "Lesson 03"
  click D2 "lessons/03-orthogonality.html" "Lesson 03"
  click D3 "lessons/03-orthogonality.html" "Lesson 03"
  click E "lessons/03-orthogonality.html" "Lesson 03"
  click F "lessons/04-history.html" "Lesson 04"
  click F1 "lessons/04-history.html" "Lesson 04"
  click F2 "lessons/04-history.html" "Lesson 04"
  click G "lessons/05-context-and-time.html" "Lesson 05"
  click G1 "lessons/05-context-and-time.html" "Lesson 05"
  click G2 "lessons/05-context-and-time.html" "Lesson 05"
  click H "lessons/05-context-and-time.html" "Lesson 05"
  click H1 "lessons/05-context-and-time.html" "Lesson 05"
  click P1 "lessons/p1-microwave.html" "P1"
  click P2 "lessons/p2-media-player.html" "P2"
  click P3 "lessons/p3-elevator.html" "P3"
  click P4 "lessons/p4-tcp.html" "P4"
  click P5 "lessons/p5-digital-watch.html" "P5"

core construct outer fringe — written, not yet studied practice problem

Calibration — not yet run

This path was built from a specification rather than from a calibration session, so nothing here is graded yet. The whole graph is on the outer fringe. Work lesson 01 and P1, then use the feedback button on each lesson and the Summarise → clipboard action to report back — the first real calibration should come out of where the problems actually bit, not out of five questions asked in advance.

Known bias to correct for: the material assumes state machines are already familiar and spends no time on the flat FSM. If that assumption is wrong, say so and lesson 01 grows a predecessor.

Lessons

01
The Configuration, Not the State
State explosion, Harel’s three additions, and the word that replaces “the current state”.
02
Depth
Compound states, the transition domain, entry/exit ordering, deepest-match priority, and the three arrows that look like loops.
P1
The Microwave Oven
10 tests · exercises/p1_microwave
03
Orthogonality
Regions, broadcast, the independence test, and scope — the box as the specification of where a feature applies.
04
History
Shallow and deep, why it lives on the arrow, and when it has to be forgotten.
P2
The Media Player
11 tests · exercises/p2_media_player
05
Context, Guards, and Run-to-Completion
What does not belong in a box, eventless transitions, the macrostep loop, and when not to use a statechart at all.
P3
The Elevator Controller
11 tests · exercises/p3_elevator
P4
TCP, Flat and Then Not
68 tests · exercises/p4_tcp
P5
Harel’s Digital Watch
15 tests · exercises/p5_digital_watch · capstone

Getting the exercises running

cd statecharts/exercises
uv venv && uv pip install python-statemachine pytest
cd p1_microwave && pytest -q

Written against python-statemachine 3.2.x using the StateChart base class (SCXML semantics), not the legacy StateMachine. exercises/README.md lists three places where 3.2.1 deviates from the specification, each found by experiment while these problems were being built. They will cost you an hour each if nobody tells you.