feat(default)!: model default(...) as a real LCA-aware transition

`default(...)` is now a transition with the same semantics as any
event-driven transition. It fires immediately after the declaring
state's entries finish and its durings start, applying the standard
exit-to-LCA / enter-to-target algorithm. Three behavioral changes
follow from this unification:

* Optional. A state with children is no longer required to declare a
  `default(...)`. When omitted, the state itself is the resting
  innermost active state; substates are reachable only via explicit
  transitions. This is the "microwave Standby" pattern — Standby
  has substates like LowPower that you enter only on demand, and
  `=> Standby;` lands at Standby itself with no descent.

* Targets anywhere. The default target may be any state in the chart
  — a child (the classic descent case), a sibling, an ancestor,
  anywhere. `default(<sibling-or-ancestor>)` exits the just-entered
  state as part of the default-fire transition; the same rule fires
  whether you wrote it for descent, redirection, or up-bounce.

* Cycle-checked at compile time. The default-edge graph (out-degree
  ≤ 1 per node) is rejected if it contains any cycle, including
  `default(self)`. `state A { default(A); }` and `A → B → A` chains
  fail to compile with a pinpoint error message naming the cycle.
  This guarantees default chains terminate at runtime.

Implementation:

* `validate.rs`: drop the "must be direct child" and "must have
  children" restrictions; add `validate_default_graph` (iterative
  three-color cycle detection via chain walk).

* `ir.rs`: keep the unresolved default ident through to
  `resolve_transitions` so non-child targets resolve against the
  global state-name map (the same map transition targets use).

* `codegen.rs`: precomputed `(from, to)` paths no longer fold default
  descent into the enter slice — each path is LCA-relative
  `(exit, enter)` ending exactly at the explicit target.
  `descend_defaults` (a parent-pointer walk) is replaced by
  `follow_defaults`, which fires real transitions through
  `apply_path` and emits `TransitionFired{Internal}` /
  `TransitionComplete` brackets per link. Up-transitions don't
  trigger default-following (nothing was freshly entered, so no
  state's default fires).

* `active_durings_per_innermost_state`: predicate widened to include
  composites without a default (they can now be the innermost active
  state, so any durings they declare must be raced when current).

BREAKING CHANGES:

* Journal format. Default-fires now emit `TransitionFired` (with
  `reason: TransitionReason::Internal`) and `TransitionComplete`
  brackets around their entry sequence. `Internal` was previously
  reserved and never emitted; it is now active. Tests that
  hand-build expected journal sequences must include these brackets
  around every default-fire.

* Validation. `default(<non-child>)` and `default` on a childless
  state previously raised compile-time errors. Both are now valid.
  Code relying on these as guard rails must adapt.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
swaitsandClaude Opus 4.7 committed 2026-04-28 20:57:01 -06:00
1 parent 2e55484080
commit 3fc0d7c57d
30 files changed
+1356 -229

No files matched your search

+36 -20
View File
@@ -37,10 +37,16 @@ Each primitive, in roughly the order a developer first meets them.
to the target, calling entries along the way.
- **Action (without transition)** — a function call attached to a trigger.
No state change. That's it.
- **Default child** — every non-leaf state declares one default child.
Whenever a state with children is entered, the default child is entered
immediately after that state's entry actions finish — it's effectively
an automatic transition into the child.
- **Default transition** — any state **may** declare one `default(...)`.
It's a transition (same LCA-aware algorithm as rule 4 / event-driven
transitions) that fires immediately after the declaring state's entry
actions finish and its durings start. The target may be any state in
the chart — a child (the classic descent case), a sibling, an
ancestor, anywhere. Defaults chain (each link is itself a transition)
until they reach a state with no default. The compiler rejects cycles
in the default graph at compile time, so every chain terminates. When
a state has no `default`, nothing else happens after entry — the
state itself is the resting innermost active state.
- **Trigger: event vs. duration** — an event is a variant of your event
enum. A duration is a timer (`after Duration` fires once, `every
Duration` fires repeatedly). Triggers attach to transitions and to
@@ -71,7 +77,8 @@ seems weird, come back to this one — it's probably the resolution.
`current_state()` returns the innermost active state, which is usually a
leaf, but can be a composite (a state with children) if you got there via
an up-transition (see below) and haven't moved since.
an up-transition (see below) and haven't moved since, or if you
transitioned into a composite that has no `default` declared.
---
@@ -121,8 +128,10 @@ To run a transition:
itself is **not** exited.
3. Walk **down** from the LCA to the target, entering each state on the
way (run entry actions → start durings). The LCA is **not** re-entered.
4. If the target has children, follow the default-child chain down to a
leaf, entering each as you go.
4. If the target declares a `default(...)`, fire it as a recursive
transition (using the same algorithm). Defaults chain until a state
with no default is reached. Compile-time cycle check guarantees
termination.
The three flavors below are just three relationships between current and
target. The same algorithm covers all of them — they only look different
@@ -131,8 +140,8 @@ in which steps fire.
### Transitioning to a sibling (or anywhere not on your active path)
The standard case. LCA is somewhere strictly above both current and
target. Exit up to LCA, enter down to target, default-descend if the
target has children. Already covered above.
target. Exit up to LCA, enter down to target, default-descend from the
target if it declares a `default`. Already covered above.
### Transitioning to yourself
@@ -153,11 +162,12 @@ Timers declared on the target restart, because the target itself was
exited and re-entered.
If the target happens to be a composite (it has children, but no child is
active right now because you got there via an up-transition), the same
default-child rule still applies on re-entry: exit the composite, re-enter
it, then descend through its default chain. Self-transitions don't add a
new rule — they're just the case where source and target are the same
state.
active right now because you got there via an up-transition or because
the composite has no `default`), the same rule still applies on re-entry:
exit the composite, re-enter it, then descend through its default chain
if it declares one. A composite without `default` is exited, re-entered,
and that's it — no further descent. Self-transitions don't add a new
rule — they're just the case where source and target are the same state.
Personally I don't find self-transitions all that valuable, but people
talk about them all the time, so they're supported.
@@ -207,7 +217,11 @@ Putting it all together:
outermost state's entry actions fire first, then its child's, and so on
down to the innermost. Within a single state, entry actions fire in
declaration order. After entry actions of a state finish, that state's
durings start. Then the default child (if any) is entered, recursively.
durings start. Then, if the state declares a `default(...)`, the
default fires as a transition (which may exit the state we just
entered if the target lies elsewhere in the chart) and the chain
continues from there. A state without `default` is the end of the
path — control stops there.
- **Exit** runs **inner-to-outer**: when leaving a path of states, the
innermost state exits first, then its parent, and so on up. Within a
single state, exit actions fire in declaration order. Before exit
@@ -367,11 +381,13 @@ drafts. Edit freely.)_
| Scenario | What fires |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Initial machine start | Root entries → default-descend down through each child's entries → durings start at each entered state. |
| Transition to sibling | Exit current up to LCA (cancel durings, run exits) → enter from LCA down to target (run entries, start durings) → default-descend if target has children. |
| Transition to self | Exit innermost (cancel durings, run exits), re-enter innermost (run entries, start durings). Timers restart. If innermost has children, default-descend after re-entry. |
| Transition to ancestor | Exit current up to (but not including) the ancestor. No entry actions. No default-descent. Ancestor's durings and timers continue. |
| Transition into a state with children | After the target's entries fire, default-descend through each default child's entries down to a leaf. |
| Initial machine start | Root entries → if root declares a `default(...)`, fire it as a transition; chain continues until a state with no default. Durings start at each entered state. |
| Transition to sibling | Exit current up to LCA (cancel durings, run exits) → enter from LCA down to target (run entries, start durings) → if target declares a `default`, fire it; chain continues. |
| Transition to self | Exit innermost (cancel durings, run exits), re-enter innermost (run entries, start durings). Timers restart. If the re-entered state declares a `default`, fire it. |
| Transition to ancestor | Exit current up to (but not including) the ancestor. No entry actions. The ancestor's `default` is **not** fired (it wasn't freshly entered). Durings and timers continue. |
| Transition into a state with `default(<descendant>)` | After the target's entries fire, the default fires as a child-direction transition (no exits at this step). The chain continues from the new innermost. |
| Transition into a state with `default(<sibling/ancestor>)` | After the target's entries fire, the default fires as a transition that exits the just-entered target and lands elsewhere. The chain continues. |
| State has no `default(...)` | After its entries fire, control stops there. The state itself is the innermost active state until something explicitly transitions away. |
| Timer fires | The declaring state's handler runs (timers don't bubble). |
| Event with no handler | Silently discarded. |
| Event handled at innermost | Innermost state's handler runs (actions in declaration order, then transition if any). |