Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 swaits
|
4ea7463089
|
||
|
swaits
|
a6d6cd2674
|
||
|
swaits
|
e183cdd95e
|
||
|
swaits
|
081bd28cca
|
No files matched your search
+15
@@ -9,6 +9,21 @@
|
||||
mutation_history.json
|
||||
*.profraw
|
||||
|
||||
# Creusot output: cargo-creusot dumps `.coma` (Coma IR) files here for
|
||||
# Why3 to read. Regenerated on every `just verify` run.
|
||||
/verif/
|
||||
|
||||
# Creusot/why3find config — `cargo creusot init` regenerates with
|
||||
# defaults appropriate to the local prover install. The `profile`
|
||||
# section caches per-machine prover timings that aren't portable.
|
||||
# `just verify` regenerates if missing.
|
||||
/why3find.json
|
||||
# why3find's per-run cache directory.
|
||||
/.why3find/
|
||||
|
||||
# Project-local Python venv created by mise's `_.python.venv` config.
|
||||
**/.venv/
|
||||
|
||||
# Local Claude Code config (per-host overrides)
|
||||
.claude/settings.local.json
|
||||
|
||||
|
||||
+149
@@ -4,6 +4,155 @@ All notable changes to this workspace are documented here. The format
|
||||
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
|
||||
this project adheres to [Semantic Versioning](https://semver.org/).
|
||||
|
||||
## 0.4.0 — 2026-04-28
|
||||
|
||||
### Changed — observability (breaking)
|
||||
|
||||
- **Unified observation pipeline.** The codegen now emits a single
|
||||
`__chart_observe!` invocation per observable atom, dispatched at
|
||||
compile time to whichever sinks are enabled: the in-memory journal
|
||||
(`feature = "journal"`), `defmt` (`trace-defmt`), `log`
|
||||
(`trace-log`), and/or `tracing` (`trace-tracing`). All sinks share
|
||||
the same vocabulary by construction — the journal IS the observation
|
||||
stream; trace backends are textual renderings of it. With NO sink
|
||||
feature on, every call site expands to `()` (zero overhead). Multiple
|
||||
trace sinks may now be enabled simultaneously (previously they were
|
||||
mutually exclusive).
|
||||
- **Trace prefix changed.** `[ChartName] verb …` →
|
||||
`[statechart:ChartName] verb …`. The new form is greppable and
|
||||
unambiguous in mixed log streams.
|
||||
- **Trace format is now logfmt-style.** Every line is
|
||||
`[statechart:Name] <verb> key=value key=value …` (or native structured
|
||||
fields under `tracing`). Twenty verbs cover every TraceEvent variant
|
||||
— entries, exits (with begin/end pairs), actions (with kind),
|
||||
durings, transitions (with **reason** showing what triggered them),
|
||||
events (received/delivered/dropped/queued/failed), timers, terminate.
|
||||
- **`trace;` keyword deprecated.** Still parsed for backwards
|
||||
compatibility, but no longer gates emission. Trace output is now
|
||||
controlled purely by which `trace-*` cargo feature you enable.
|
||||
|
||||
### Changed — journal (breaking)
|
||||
|
||||
- **`TraceEvent::TransitionFired` carries `reason: TransitionReason`.**
|
||||
Replay consumers now see whether a transition was driven by an event
|
||||
(`Event { event: u16 }`), a timer (`Timer { state, timer }`), or
|
||||
internal logic (`Internal`).
|
||||
- **New TraceEvent variants for phase begin/end pairing.**
|
||||
- `EnterBegan { state }` fires before a state's entry actions /
|
||||
timers / durings; `Entered` keeps its place as the end marker.
|
||||
- `ExitBegan { state }` fires before a state's during cancellations
|
||||
/ timer cancellations / exit actions; `Exited` keeps its place as
|
||||
the end marker.
|
||||
- `TransitionComplete { from, to }` fires after a transition's full
|
||||
exit-then-enter sequence finishes; pairs with `TransitionFired`.
|
||||
- `EventReceived { event }` fires when an event is popped from the
|
||||
queue, before handler search; pairs with `EventDelivered` /
|
||||
`EventDropped` / `TerminateRequested`.
|
||||
|
||||
### Added
|
||||
|
||||
- **`hsmc/tests/trace_format.rs`** — 11 tests pinning every verb's
|
||||
exact textual rendering, including a journal/trace atom-count
|
||||
equivalence test.
|
||||
- **`TransitionReason`** enum — re-exported from the crate root when
|
||||
`feature = "journal"` is on. Carried on `TraceEvent::TransitionFired`.
|
||||
- **Multiple trace backends compose.** Previously enabling more than
|
||||
one of `trace-defmt` / `trace-log` / `trace-tracing` was a compile
|
||||
error. Now they fan out independently.
|
||||
|
||||
### Migration
|
||||
|
||||
Chart syntax is unchanged: every v0.1 / v0.2 / v0.3 statechart compiles
|
||||
under v0.4 without modification. Breakage is confined to the
|
||||
observability surface area:
|
||||
|
||||
1. **Trace line prefix.** Update grep patterns and log filters from
|
||||
`[ChartName]` to `[statechart:ChartName]`. The verb after the
|
||||
prefix is now a single hyphenated token followed by `key=value`
|
||||
pairs.
|
||||
|
||||
2. **`TraceEvent::TransitionFired`** has a new `reason` field. Update
|
||||
pattern matches:
|
||||
|
||||
```rust
|
||||
// before:
|
||||
TraceEvent::TransitionFired { from, to } => …
|
||||
// after:
|
||||
TraceEvent::TransitionFired { from, to, reason } => …
|
||||
// or, if you don't care:
|
||||
TraceEvent::TransitionFired { from, to, .. } => …
|
||||
```
|
||||
|
||||
3. **New `TraceEvent` variants.** If you `match` exhaustively, add
|
||||
arms for `EnterBegan`, `ExitBegan`, `TransitionComplete`,
|
||||
`EventReceived`. Otherwise nothing changes.
|
||||
|
||||
4. **`trace;` keyword is now a no-op.** Charts that declared it still
|
||||
compile. Trace output is now controlled purely by which `trace-*`
|
||||
cargo feature you enable.
|
||||
|
||||
5. **`__chart_trace!` and `__chart_journal!` macros are removed.**
|
||||
These were doc-hidden and not part of the public API; mentioned
|
||||
here for codebases that grepped through the macro emission for
|
||||
patches/forks.
|
||||
|
||||
## 0.3.0 — 2026-04-27
|
||||
|
||||
### Added
|
||||
|
||||
- **`journal` Cargo feature.** Records every observable atom of chart
|
||||
execution — `Started`, `Entered`, `Exited`, `ActionInvoked`
|
||||
(`Entry`/`Exit`/`Handler`), `DuringStarted`, `DuringCancelled`,
|
||||
`TransitionFired`, `EventDelivered`, `EventDropped`, `EmitQueued`,
|
||||
`EmitFailed`, `TimerArmed`, `TimerCancelled`, `TimerFired`,
|
||||
`TerminateRequested`, `Terminated` — into a `Vec<TraceEvent>` on the
|
||||
generated machine. Same chart + same events = byte-identical
|
||||
journal. Public API: `journal()`, `take_journal()`, `clear_journal()`,
|
||||
`CHART_HASH` (a stable FNV-1a fingerprint of the chart's structural
|
||||
definition).
|
||||
- **Root state targetable by chart name.** `on(Trig) => MyChart;`
|
||||
resolves to the root state in both `classify_target` and
|
||||
`resolve_transitions`. From any nested state this is an
|
||||
up-transition (root is always on the active path).
|
||||
- **113 deterministic-flow tests** (under `--features tokio,journal`)
|
||||
comparing hand-built expected journals byte-for-byte against
|
||||
actual, anchored to spec sections: initial entry, lateral / self /
|
||||
up transitions, default-descent, event bubbling, timer arm /
|
||||
cancel / fire, emit, ordering, durings, step-vs-dispatch
|
||||
equivalence, root-targeting, `current_state()`, termination.
|
||||
- **`verification/` workspace member with Creusot proofs.** Verified
|
||||
mirrors of the runtime `EventQueue` and `TimerTable` carry
|
||||
`creusot-std` (Pearlite) contracts that Why3 + alt-ergo + z3
|
||||
discharge mechanically. 14/14 VCs proven. `just verify` is
|
||||
self-installing (mise pulls opam + the pinned nightly + Creusot's
|
||||
canonical `INSTALL`).
|
||||
- **`docs/002. hsmc-semantics-formal.md`** — canonical, unambiguous
|
||||
reference for chart behavior. Numbered S-rules supersede the v0.1
|
||||
prose spec and v0.2 design-change-request.
|
||||
- **README "How a chart behaves" section** — eight building-block
|
||||
rules that build on each other, with an explicit "what hsmc
|
||||
deliberately does NOT have" table.
|
||||
|
||||
### Tooling
|
||||
|
||||
- `mise.toml` (root) declares stable Rust + components + embedded
|
||||
targets + cargo subcommands. `verification/mise.toml` declares
|
||||
the pinned `nightly-2025-11-13` + opam + python venv + uv.
|
||||
- `set shell` and `set script-interpreter` route every `just` recipe
|
||||
through `mise exec` — no shebangs, no per-recipe wrappers.
|
||||
- `just verify` runs `cargo creusot prove --no-cache` so SMT
|
||||
invocations happen on every run; `time` shows ~7s CPU on ~1.2s
|
||||
wall = real parallel work.
|
||||
- `just mutants` runs with `--features tokio,journal` so `journal_*`
|
||||
and `det_*` tests execute. **0 missed mutants.**
|
||||
- `just miri` excludes `hsmc-macros` (trybuild glob hits Miri's
|
||||
isolation) and `hsmc-verification` (different pinned toolchain).
|
||||
66 tests pass under Miri, 0 UB.
|
||||
|
||||
### Backward compatibility
|
||||
|
||||
Every v0.1 / v0.2 statechart compiles under v0.3 unchanged.
|
||||
|
||||
## 0.2.0 — 2026-04-22
|
||||
|
||||
### Fixed — behavior-visible (breaking)
|
||||
|
||||
Generated
+188
-6
@@ -8,6 +8,18 @@ version = "0.2.21"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
|
||||
|
||||
[[package]]
|
||||
name = "autocfg"
|
||||
version = "1.5.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
|
||||
|
||||
[[package]]
|
||||
name = "bitflags"
|
||||
version = "1.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
|
||||
|
||||
[[package]]
|
||||
name = "bitflags"
|
||||
version = "2.11.1"
|
||||
@@ -55,6 +67,27 @@ dependencies = [
|
||||
"static_assertions",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "creusot-std"
|
||||
version = "0.9.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "2b6989d2fc081ac6e3f08fe18e4461b29b3e72fbcba78058131892d000f06bab"
|
||||
dependencies = [
|
||||
"creusot-std-proc",
|
||||
"num-rational",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "creusot-std-proc"
|
||||
version = "0.9.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3f41572ae8e96468a0eb0411dbdf1defc4896287672041ca3c3c161c4e09c57d"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "critical-section"
|
||||
version = "1.2.0"
|
||||
@@ -67,7 +100,7 @@ version = "0.28.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "829d955a0bb380ef178a640b91779e3987da38c9aea133b20614cfed8cdea9c6"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"bitflags 2.11.1",
|
||||
"crossterm_winapi",
|
||||
"futures-core",
|
||||
"mio",
|
||||
@@ -121,6 +154,47 @@ dependencies = [
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "defmt"
|
||||
version = "0.3.100"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f0963443817029b2024136fc4dd07a5107eb8f977eaf18fcd1fdeb11306b64ad"
|
||||
dependencies = [
|
||||
"defmt 1.0.1",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "defmt"
|
||||
version = "1.0.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "548d977b6da32fa1d1fda2876453da1e7df63ad0304c8b3dae4dbe7b96f39b78"
|
||||
dependencies = [
|
||||
"bitflags 1.3.2",
|
||||
"defmt-macros",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "defmt-macros"
|
||||
version = "1.0.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3d4fc12a85bcf441cfe44344c4b72d58493178ce635338a3f3b78943aceb258e"
|
||||
dependencies = [
|
||||
"defmt-parser",
|
||||
"proc-macro-error2",
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "defmt-parser"
|
||||
version = "1.0.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "10d60334b3b2e7c9d91ef8150abfb6fa4c1c39ebbcf4a81c2e346aad939fee3e"
|
||||
dependencies = [
|
||||
"thiserror",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "document-features"
|
||||
version = "0.2.12"
|
||||
@@ -391,23 +465,26 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
|
||||
|
||||
[[package]]
|
||||
name = "hsmc"
|
||||
version = "0.2.0"
|
||||
version = "0.4.0"
|
||||
dependencies = [
|
||||
"crossterm",
|
||||
"defmt 0.3.100",
|
||||
"embassy-futures",
|
||||
"embassy-sync",
|
||||
"embassy-time",
|
||||
"futures",
|
||||
"heapless 0.8.0",
|
||||
"hsmc-macros",
|
||||
"log",
|
||||
"ratatui",
|
||||
"tokio",
|
||||
"tracing",
|
||||
"trybuild",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "hsmc-macros"
|
||||
version = "0.2.0"
|
||||
version = "0.4.0"
|
||||
dependencies = [
|
||||
"hsmc",
|
||||
"proc-macro2",
|
||||
@@ -416,6 +493,14 @@ dependencies = [
|
||||
"trybuild",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "hsmc-verification"
|
||||
version = "0.4.0"
|
||||
dependencies = [
|
||||
"creusot-std",
|
||||
"hsmc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "ident_case"
|
||||
version = "1.0.1"
|
||||
@@ -544,6 +629,45 @@ version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8d5439c4ad607c3c23abf66de8c8bf57ba8adcd1f129e699851a6e43935d339d"
|
||||
|
||||
[[package]]
|
||||
name = "num-bigint"
|
||||
version = "0.4.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a5e44f723f1133c9deac646763579fdb3ac745e418f2a7af9cd0c431da1f20b9"
|
||||
dependencies = [
|
||||
"num-integer",
|
||||
"num-traits",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "num-integer"
|
||||
version = "0.1.46"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
|
||||
dependencies = [
|
||||
"num-traits",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "num-rational"
|
||||
version = "0.4.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"
|
||||
dependencies = [
|
||||
"num-bigint",
|
||||
"num-integer",
|
||||
"num-traits",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "num-traits"
|
||||
version = "0.2.19"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
|
||||
dependencies = [
|
||||
"autocfg",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "parking_lot"
|
||||
version = "0.12.5"
|
||||
@@ -579,6 +703,28 @@ version = "0.2.17"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
|
||||
|
||||
[[package]]
|
||||
name = "proc-macro-error-attr2"
|
||||
version = "2.0.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "96de42df36bb9bba5542fe9f1a054b8cc87e172759a1868aa05c1f3acc89dfc5"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "proc-macro-error2"
|
||||
version = "2.0.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "11ec05c52be0a07b08061f7dd003e7d7092e0472bc731b4af7bb1ef876109802"
|
||||
dependencies = [
|
||||
"proc-macro-error-attr2",
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "proc-macro2"
|
||||
version = "1.0.106"
|
||||
@@ -603,7 +749,7 @@ version = "0.28.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "fdef7f9be5c0122f890d58bdf4d964349ba6a6161f705907526d891efabba57d"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"bitflags 2.11.1",
|
||||
"cassowary",
|
||||
"compact_str",
|
||||
"crossterm",
|
||||
@@ -624,7 +770,7 @@ version = "0.5.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"bitflags 2.11.1",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -633,7 +779,7 @@ version = "0.38.44"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"bitflags 2.11.1",
|
||||
"errno",
|
||||
"libc",
|
||||
"linux-raw-sys",
|
||||
@@ -818,6 +964,26 @@ dependencies = [
|
||||
"winapi-util",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "thiserror"
|
||||
version = "2.0.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
|
||||
dependencies = [
|
||||
"thiserror-impl",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "thiserror-impl"
|
||||
version = "2.0.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tokio"
|
||||
version = "1.52.0"
|
||||
@@ -878,6 +1044,22 @@ version = "1.1.1+spec-1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "756daf9b1013ebe47a8776667b466417e2d4c5679d441c26230efd9ef78692db"
|
||||
|
||||
[[package]]
|
||||
name = "tracing"
|
||||
version = "0.1.44"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
|
||||
dependencies = [
|
||||
"pin-project-lite",
|
||||
"tracing-core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tracing-core"
|
||||
version = "0.1.36"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
|
||||
|
||||
[[package]]
|
||||
name = "trybuild"
|
||||
version = "1.0.116"
|
||||
|
||||
+2
-2
@@ -1,9 +1,9 @@
|
||||
[workspace]
|
||||
resolver = "2"
|
||||
members = ["hsmc", "hsmc-macros"]
|
||||
members = ["hsmc", "hsmc-macros", "verification"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.2.0"
|
||||
version = "0.4.0"
|
||||
edition = "2021"
|
||||
license = "MIT OR Apache-2.0"
|
||||
authors = ["Stephen Waits <steve@waits.net>"]
|
||||
|
||||
@@ -40,8 +40,159 @@ statechart! {
|
||||
- **`m.run().await` is the whole task body.** Races active durings, the
|
||||
external event channel, and timer deadlines. The MCU sleeps between
|
||||
events (embassy's cooperative executor parks all futures).
|
||||
- **Backward-compatible.** Every v0.1 statechart compiles under v0.2
|
||||
unchanged.
|
||||
- **Unified observability.** One observation per atom of execution
|
||||
fans out at compile time to a journal (`Vec<TraceEvent>`) and/or
|
||||
textual trace backends (`defmt`, `log`, `tracing`) — they share a
|
||||
single vocabulary, so they cannot diverge. With no sink feature on,
|
||||
every site expands to `()` (zero overhead). See
|
||||
[Observability](#observability--one-journal-multiple-outputs).
|
||||
- **Deterministic + mechanically verified.** The `journal` feature
|
||||
records every action, transition, timer, and event in order — same
|
||||
inputs, byte-identical journal. The runtime queue and timer table
|
||||
carry Pearlite specs that Creusot + Why3 + alt-ergo + z3 discharge
|
||||
mechanically (`just verify`). 159 tests pin every spec rule
|
||||
(journal sequences + trace-format regression + integration).
|
||||
- **Backward-compatible chart syntax.** Every v0.1 / v0.2 / v0.3
|
||||
statechart compiles under v0.4 unchanged. The 0.4 breaks are in
|
||||
observability surface area only — see
|
||||
[Migration](#migration-from-v03).
|
||||
|
||||
## How a chart behaves — the building blocks
|
||||
|
||||
Eight rules, each building on the previous. Internalize these and every
|
||||
edge case below falls out — you don't have to memorize anything else.
|
||||
|
||||
The full canonical reference lives at
|
||||
[`docs/002. hsmc-semantics-formal.md`](docs/002.%20hsmc-semantics-formal.md);
|
||||
this section is the on-ramp.
|
||||
|
||||
### 1. The active path — you are in every state from root to leaf
|
||||
|
||||
At any moment, the machine is in a **path** of states from the root down
|
||||
to one innermost state. If you're in `C` inside `B` inside `A`, you're
|
||||
**simultaneously** in `Root`, `A`, `B`, and `C`. The root is always
|
||||
active until termination.
|
||||
|
||||
This is the most important rule. Every rule below is downstream of it.
|
||||
If a behavior somewhere else seems weird, come back here — it's
|
||||
probably the resolution.
|
||||
|
||||
### 2. Default-descent — composites auto-enter their default child
|
||||
|
||||
Every state with children declares one `default(...)`. When a composite
|
||||
state is entered, its entry actions run first, **then** the default
|
||||
child is entered, recursively, until a leaf.
|
||||
|
||||
So `Root` with `default(A)` and `A` with `default(B)` means: the
|
||||
machine starts by entering `Root` → `A` → `B`, all on first step.
|
||||
|
||||
### 3. Event bubbling — leaf first, first handler wins
|
||||
|
||||
An event arrives. Search starts at the **innermost** active state. If
|
||||
that state has a handler, it runs and the event is consumed. If not,
|
||||
walk up to the parent and check there. Repeat. If you reach the root
|
||||
with no handler, the event is silently discarded.
|
||||
|
||||
Three corollaries:
|
||||
|
||||
- Leaf shadows ancestor for the same trigger.
|
||||
- Multiple handlers in one state on the same trigger fire in
|
||||
declaration order; the transition (if any) fires last.
|
||||
- **Timers don't bubble.** A timer belongs to the state that declared
|
||||
it; it fires only in that state's scope.
|
||||
|
||||
### 4. Transitions — exit to LCA, enter to target
|
||||
|
||||
Any transition's algorithm is uniform:
|
||||
|
||||
1. Find the LCA (lowest common ancestor) of current and target.
|
||||
2. Walk **up** from current, exiting each state, until you hit the LCA.
|
||||
The LCA itself is **not** exited.
|
||||
3. Walk **down** from the LCA to target, entering each state. The LCA
|
||||
is **not** re-entered.
|
||||
4. If target has children, default-descend (rule 2).
|
||||
|
||||
The LCA always exists because root is always an upper bound. State
|
||||
names are globally unique across the chart, so a transition can target
|
||||
**any** state — siblings, cousins, ancestors, the root itself
|
||||
(`on(Trig) => MyChart;`).
|
||||
|
||||
### 5. The up-transition rule — never re-enter what you never left
|
||||
|
||||
If your transition target is **already on the active path** (i.e., it's
|
||||
an ancestor of the innermost state), then steps 3 and 4 of the
|
||||
transition algorithm do nothing. You exit the states strictly between
|
||||
current and target; the target itself is **not** re-entered.
|
||||
|
||||
So from leaf `C` inside `B` inside `A`, an `on(Up) => A;` exits `C`
|
||||
then `B`. `A`'s entry actions don't fire. `A`'s `default` is not
|
||||
followed. `A`'s timers don't restart. `A`'s durings keep running.
|
||||
|
||||
You cannot enter a state you never left.
|
||||
|
||||
### 6. Entry / exit ordering
|
||||
|
||||
Direction is set by the path:
|
||||
|
||||
- **Entries** fire **outer-to-inner**: when entering down through a
|
||||
path, the outermost state's entries fire first, then the next, then
|
||||
the leaf's. Within a single state, entry actions fire in declaration
|
||||
order. After a state's entries finish, its `during:` activities
|
||||
start. Then default-descent (rule 2) applies recursively.
|
||||
- **Exits** fire **inner-to-outer**: leaf first, then parent, then
|
||||
grandparent. Within a single state, exit actions fire in declaration
|
||||
order. Before a state's exits begin, its `during:` activities are
|
||||
cancelled.
|
||||
|
||||
So a full transition reads: cancel durings on the way out → run exits
|
||||
on the way out → run entries on the way in → start durings on the way
|
||||
in.
|
||||
|
||||
### 7. Timers — armed by state lifecycle
|
||||
|
||||
A timer (`on(after D) => …` or `on(every D) => …`) is **armed** when
|
||||
its declaring state is entered, **cancelled** when that state is
|
||||
exited. Descending into a child is _not_ an exit, so the parent's
|
||||
timers keep running while you're in a child. Re-entering a state
|
||||
restarts its timers from zero.
|
||||
|
||||
### 8. emit / during / termination — all built on the rules above
|
||||
|
||||
- **`emit(ev)`** from inside an action queues an event. The runtime
|
||||
finishes the current event's handling — including every entry/exit
|
||||
in the resulting transition — **before** dequeuing the new event.
|
||||
No re-entrant dispatch.
|
||||
- **`during:`** is an async future tied to its state's lifecycle. It
|
||||
starts after the state's entry actions finish and is cancelled (the
|
||||
future is dropped) before the state's exit actions begin. Multiple
|
||||
durings on the active path race; each borrows disjoint `&mut` fields
|
||||
of the context (Rust's split-borrow checker enforces this at compile
|
||||
time).
|
||||
- **Termination** is just rules 6 + 4 with target = "outside the
|
||||
chart": exit the entire active path inner-to-outer, then stop.
|
||||
Pending events drop. In-flight durings drop at their next `.await`.
|
||||
|
||||
That's the whole behavior model. The
|
||||
[full semantics doc](docs/002.%20hsmc-semantics-formal.md)
|
||||
spells out edge cases (queue overflow surfacing, same-tick timer ties,
|
||||
self-transitions on composites) but the rules above cover the
|
||||
overwhelming majority of charts.
|
||||
|
||||
### What `hsmc` deliberately does NOT have
|
||||
|
||||
The bet is on **simple, consistent semantics**. These features are
|
||||
omitted on purpose; for each, what to do instead:
|
||||
|
||||
| Missing feature | Use instead |
|
||||
| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| Guard conditions on transitions | Split source into two states, or have an action `emit()` a follow-up event for the chart to branch on |
|
||||
| Orthogonal / parallel regions | Two charts as two tasks connected by channels, or multiple `during:` activities in one state |
|
||||
| History states | Store last child explicitly in your context; transition to it on re-entry |
|
||||
| Deferred events | Handle where they arrive (drop/log if not relevant), or have producer check state |
|
||||
| Internal transitions | `action(Trig) => fn;` (no transition) — exactly that |
|
||||
| State-local context | All state in the root context; durings borrow disjoint fields |
|
||||
| Event priorities beyond FIFO | Higher-priority events on a separate channel into a separate, faster machine |
|
||||
| Runtime statechart modification | Design every variation up front as states |
|
||||
|
||||
## Quickstart
|
||||
|
||||
@@ -49,7 +200,7 @@ Add to `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
hsmc = { version = "0.2", features = ["embassy"] } # or ["tokio"]
|
||||
hsmc = { version = "0.4", features = ["embassy"] } # or ["tokio"]
|
||||
```
|
||||
|
||||
Minimal timer-only machine:
|
||||
@@ -185,45 +336,100 @@ into a single during that uses `select` internally.
|
||||
|
||||
For `statechart! Foo { ... }` the macro emits:
|
||||
|
||||
| Item | What it is |
|
||||
|---------------------------------|----------------------------------------------------------------------|
|
||||
| `FooState` | Enum of every user-declared state. |
|
||||
| `FooActions` | Trait with one async fn per unique action name. User implements. |
|
||||
| `FooActionContext<'a>` | Wrapper passed to actions. `Deref`s to the root context. `emit()`. |
|
||||
| `FooCtx<'a>` | Type alias for `FooActionContext<'a>`. |
|
||||
| `Foo<const QN: usize = 8>` | The machine itself. |
|
||||
| `FooSender` | Cloneable handle for cross-task / ISR event injection. |
|
||||
| `Foo::<8>::STATE_CHART` | `&'static str` ASCII tree of the hierarchy (useful for `defmt`/docs).|
|
||||
| Item | What it is |
|
||||
| -------------------------- | --------------------------------------------------------------------- |
|
||||
| `FooState` | Enum of every user-declared state. |
|
||||
| `FooActions` | Trait with one async fn per unique action name. User implements. |
|
||||
| `FooActionContext<'a>` | Wrapper passed to actions. `Deref`s to the root context. `emit()`. |
|
||||
| `FooCtx<'a>` | Type alias for `FooActionContext<'a>`. |
|
||||
| `Foo<const QN: usize = 8>` | The machine itself. |
|
||||
| `FooSender` | Cloneable handle for cross-task / ISR event injection. |
|
||||
| `Foo::<8>::STATE_CHART` | `&'static str` ASCII tree of the hierarchy (useful for `defmt`/docs). |
|
||||
|
||||
### Machine methods
|
||||
|
||||
| Method | Notes |
|
||||
|-------------------------------------|------------------------------------------------------------------|
|
||||
| `new(ctx)` / `new(ctx, channel)` | Construct. Under embassy, pass an `&'static Channel`. |
|
||||
| `with_queue_capacity::<N>(ctx,...)` | Custom event-queue capacity. |
|
||||
| `async fn run()` | Drive the machine to completion (async features). |
|
||||
| `async fn dispatch(ev)` | Push event + drain to quiescence. Same task injection. |
|
||||
| `fn step(elapsed) -> Option<Duration>` | One unit of work (test/polling driver). |
|
||||
| `fn send(ev)` | Raw push, non-draining. For tests. |
|
||||
| `sender() -> Sender` | Clone handle for other tasks / ISRs. |
|
||||
| `current_state()` | The active leaf state. |
|
||||
| `is_terminated()` | True after `terminate` event. |
|
||||
| `has_pending_events()` | Queue non-empty. |
|
||||
| `context()` / `context_mut()` | Borrow the root context. |
|
||||
| `into_context(self)` | Consume, return ctx. |
|
||||
| `STATE_CHART` | Const ASCII diagram. |
|
||||
| Method | Notes |
|
||||
| -------------------------------------- | ------------------------------------------------------ |
|
||||
| `new(ctx)` / `new(ctx, channel)` | Construct. Under embassy, pass an `&'static Channel`. |
|
||||
| `with_queue_capacity::<N>(ctx,...)` | Custom event-queue capacity. |
|
||||
| `async fn run()` | Drive the machine to completion (async features). |
|
||||
| `async fn dispatch(ev)` | Push event + drain to quiescence. Same task injection. |
|
||||
| `fn step(elapsed) -> Option<Duration>` | One unit of work (test/polling driver). |
|
||||
| `fn send(ev)` | Raw push, non-draining. For tests. |
|
||||
| `sender() -> Sender` | Clone handle for other tasks / ISRs. |
|
||||
| `current_state()` | The active leaf state. |
|
||||
| `is_terminated()` | True after `terminate` event. |
|
||||
| `has_pending_events()` | Queue non-empty. |
|
||||
| `context()` / `context_mut()` | Borrow the root context. |
|
||||
| `into_context(self)` | Consume, return ctx. |
|
||||
| `STATE_CHART` | Const ASCII diagram. |
|
||||
|
||||
## Feature flags
|
||||
|
||||
| Feature | Effect |
|
||||
|-----------|-------------------------------------------------------------------------|
|
||||
| (default) | `no_std`, no async runtime. Drive via `step(Duration)` + `send(ev)`. |
|
||||
| `tokio` | Async actions + `run()`. Targets single-thread via `LocalSet`. |
|
||||
| `embassy` | Async actions + `run()`. Targets embassy's cooperative executor. `no_std`.|
|
||||
| Feature | Effect |
|
||||
| --------- | -------------------------------------------------------------------------- |
|
||||
| (default) | `no_std`, no async runtime. Drive via `step(Duration)` + `send(ev)`. |
|
||||
| `tokio` | Async actions + `run()`. Targets single-thread via `LocalSet`. |
|
||||
| `embassy` | Async actions + `run()`. Targets embassy's cooperative executor. `no_std`. |
|
||||
|
||||
`embassy` and `tokio` are mutually exclusive — enabling both is a compile
|
||||
error.
|
||||
|
||||
## Migration from v0.3
|
||||
|
||||
The 0.4 breaks are in the observability surface area only; chart
|
||||
syntax and runtime API are unchanged.
|
||||
|
||||
### 1. Trace prefix changed
|
||||
|
||||
Trace lines (when `trace-defmt` / `trace-log` / `trace-tracing` is
|
||||
enabled) now use `[statechart:Name]` instead of `[Name]`. Update any
|
||||
log filters or grep patterns. The verb after the prefix is now a
|
||||
single hyphenated token followed by `key=value` pairs (logfmt).
|
||||
|
||||
### 2. `TraceEvent::TransitionFired` carries `reason`
|
||||
|
||||
Add `reason` to any pattern matches:
|
||||
|
||||
```rust
|
||||
// before:
|
||||
TraceEvent::TransitionFired { from, to } => …
|
||||
// after:
|
||||
TraceEvent::TransitionFired { from, to, reason } => …
|
||||
// or, if you don't need it:
|
||||
TraceEvent::TransitionFired { from, to, .. } => …
|
||||
```
|
||||
|
||||
The new field carries `TransitionReason::Event { event }`,
|
||||
`Timer { state, timer }`, or `Internal` so consumers can see what
|
||||
triggered the transition.
|
||||
|
||||
### 3. New `TraceEvent` variants
|
||||
|
||||
If you `match` exhaustively on `TraceEvent`, add arms for the new
|
||||
variants. Otherwise nothing changes:
|
||||
|
||||
- `EnterBegan { state }` — phase begin marker pairs with `Entered`.
|
||||
- `ExitBegan { state }` — phase begin marker pairs with `Exited`.
|
||||
- `TransitionComplete { from, to }` — pairs with `TransitionFired`.
|
||||
- `EventReceived { event }` — fires when an event is popped from the
|
||||
queue, before handler search.
|
||||
|
||||
These are pure observation — no runtime semantic change.
|
||||
|
||||
### 4. `trace;` keyword is a no-op
|
||||
|
||||
Charts that declared `trace;` continue to compile. The keyword no
|
||||
longer gates emission — observation is now controlled purely by
|
||||
which `trace-*` cargo feature you enable. You can leave `trace;` in
|
||||
or remove it; both work.
|
||||
|
||||
### 5. Trace backends are no longer mutually exclusive
|
||||
|
||||
Previously, enabling more than one of `trace-defmt` / `trace-log` /
|
||||
`trace-tracing` was a compile error. Now they fan out independently:
|
||||
turn on whichever you want.
|
||||
|
||||
## Migration from v0.1
|
||||
|
||||
v0.1 statecharts continue to compile. New features are purely additive:
|
||||
@@ -300,24 +506,130 @@ async fn radio_task(lora: LoRaDriver, ch: &'static RadioChan) {
|
||||
|
||||
## Examples
|
||||
|
||||
| Example | Purpose |
|
||||
|--------------------|---------------------------------------------------------------------|
|
||||
| `microwave` | Full-feature pure-event machine: entry/exit, timers, emit, terminate.|
|
||||
| `microwave_tui` | TUI variant of microwave. |
|
||||
| `during_radio` | `during:` activities simulating a radio task with RX + TX loops. |
|
||||
| `embassy_full` | Embassy feature demonstration. |
|
||||
| Example | Purpose |
|
||||
| --------------- | --------------------------------------------------------------------- |
|
||||
| `microwave` | Full-feature pure-event machine: entry/exit, timers, emit, terminate. |
|
||||
| `microwave_tui` | TUI variant of microwave. |
|
||||
| `during_radio` | `during:` activities simulating a radio task with RX + TX loops. |
|
||||
| `embassy_full` | Embassy feature demonstration. |
|
||||
|
||||
Run `cargo run --example during_radio --features tokio` to see the
|
||||
`during:` pattern end-to-end.
|
||||
|
||||
## Verification
|
||||
|
||||
`hsmc` ships with a Creusot deductive-verification crate
|
||||
(`verification/`) that proves the runtime's `EventQueue` and
|
||||
`TimerTable` correct against Pearlite specs. Why3 + alt-ergo + z3
|
||||
discharge every VC mechanically. Run:
|
||||
|
||||
```bash
|
||||
just verify
|
||||
```
|
||||
|
||||
The recipe is self-installing (mise pulls in the pinned nightly,
|
||||
opam, Why3, the SMT solvers, and `cargo-creusot`) so a fresh clone
|
||||
gets to a green proof in one command. See
|
||||
[`verification/INVARIANTS.md`](verification/INVARIANTS.md) for the
|
||||
spec-rule → proof mapping.
|
||||
|
||||
Beyond Creusot, the suite includes:
|
||||
|
||||
- **159 integration tests** — full chart behavior, byte-equal expected-
|
||||
vs-actual journals for ~113 deterministic-flow tests, plus 11 trace-
|
||||
format regression tests pinning every observation verb's exact
|
||||
textual rendering.
|
||||
- **0 missed mutants** under `cargo mutants --features
|
||||
tokio,journal,trace-log`.
|
||||
- **Miri**: 68 tests, no UB.
|
||||
|
||||
## Observability — one journal, multiple outputs
|
||||
|
||||
Every chart emits a single observation per atom of execution. That
|
||||
observation fans out to whichever sinks you compile in:
|
||||
|
||||
| Feature | Sink |
|
||||
| --------------- | -------------------------------------------------------- |
|
||||
| `journal` | In-memory `Vec<TraceEvent>` (replay, byte-deterministic) |
|
||||
| `trace-defmt` | `defmt::*` log lines |
|
||||
| `trace-log` | `log::*` log lines |
|
||||
| `trace-tracing` | `tracing::*` events with structured fields |
|
||||
|
||||
With **no** sink feature on, observation is fully elided at compile
|
||||
time — zero overhead. Multiple sinks can be enabled simultaneously;
|
||||
the journal IS the observation stream and trace backends are textual
|
||||
renderings of it, so they cannot diverge.
|
||||
|
||||
The textual format is logfmt-style — greppable and regex-parseable:
|
||||
|
||||
```
|
||||
[statechart:Microwave] started chart_hash=0xa1b2c3d4
|
||||
[statechart:Microwave] entering state=Idle
|
||||
[statechart:Microwave] action state=Idle action=clear_display kind=entry
|
||||
[statechart:Microwave] timer-armed state=Idle timer=t0 duration_ns=5000000000
|
||||
[statechart:Microwave] during-started state=Idle during=poll_sensor
|
||||
[statechart:Microwave] entered state=Idle
|
||||
[statechart:Microwave] event-received name=StartButton
|
||||
[statechart:Microwave] event-delivered name=StartButton handler=Idle
|
||||
[statechart:Microwave] transition-begin from=Idle to=Heating reason=event:StartButton
|
||||
[statechart:Microwave] exiting state=Idle
|
||||
[statechart:Microwave] timer-cancelled state=Idle timer=t0
|
||||
[statechart:Microwave] during-cancelled state=Idle during=poll_sensor
|
||||
[statechart:Microwave] action state=Idle action=stop_motor kind=exit
|
||||
[statechart:Microwave] exited state=Idle
|
||||
[statechart:Microwave] entering state=Heating
|
||||
[statechart:Microwave] entered state=Heating
|
||||
[statechart:Microwave] transition-complete from=Idle to=Heating
|
||||
```
|
||||
|
||||
### The verb vocabulary
|
||||
|
||||
Twenty verbs cover every `TraceEvent` variant. Begin/end markers
|
||||
bracket entry, exit, and transition phases so the actions, timers,
|
||||
and durings running inside each phase are visible.
|
||||
|
||||
| Verb | Fires when |
|
||||
|---|---|
|
||||
| `started` | First step of a chart's life — carries `chart_hash` |
|
||||
| `entering` / `entered` | Begin / end of a state's entry phase |
|
||||
| `exiting` / `exited` | Begin / end of a state's exit phase |
|
||||
| `action` | An action fn was called — `kind=entry\|exit\|handler` |
|
||||
| `during-started` / `during-cancelled` | A `during:` activity started / was dropped |
|
||||
| `transition-begin` / `transition-complete` | Begin / end of a transition's exit-then-enter sequence |
|
||||
| `event-received` | An event was popped from the queue |
|
||||
| `event-delivered` | A handler ran for the event |
|
||||
| `event-dropped` | The event reached root with no handler |
|
||||
| `emit-queued` / `emit-failed` | `emit()` from inside an action — queued or rejected |
|
||||
| `timer-armed` / `timer-cancelled` / `timer-fired` | Timer lifecycle |
|
||||
| `terminate-requested` | `terminate(...)` event matched, exit chain about to run |
|
||||
| `terminated` | Chart finished (always last) |
|
||||
|
||||
The `reason=` field on `transition-begin` records what triggered the
|
||||
transition: an event (`event:VariantName`), a timer
|
||||
(`timer:State/timer-id`), or `internal`. Real-life captures can be
|
||||
diffed against expected behavior the same way the journal can.
|
||||
|
||||
## Status
|
||||
|
||||
- v0.1 spec: fully implemented.
|
||||
- v0.2 additions: `during:`, optional `events:`, `dispatch()`, `STATE_CHART`,
|
||||
drain-on-send.
|
||||
- Out of scope: state-scoped context types (hierarchy), guard conditions,
|
||||
orthogonal/parallel regions, history states, runtime statechart
|
||||
modification, multi-threaded tokio.
|
||||
- v0.2: `during:`, optional `events:`, `dispatch()`, `STATE_CHART`,
|
||||
drain-on-send. Up-transitions no longer exit/re-enter the target.
|
||||
- v0.3: `journal` feature + deterministic trace + replay; root
|
||||
state targetable by chart name; Creusot verification of the
|
||||
runtime data structures; 113-test deterministic-flow suite.
|
||||
- v0.4: unified observation pipeline (journal + trace share one
|
||||
vocabulary, fan out to multiple sinks at compile time); logfmt-
|
||||
style trace format with `[statechart:Name]` prefix; transition
|
||||
reasons; entry/exit/transition begin/end markers; multiple trace
|
||||
backends now compose; chart-level `trace;` keyword deprecated.
|
||||
Breaking on the `TraceEvent` enum shape; chart syntax unchanged.
|
||||
- Out of scope (deliberate): guard conditions, orthogonal/parallel
|
||||
regions, history states, deferred events, internal transitions,
|
||||
state-local context, event priorities beyond FIFO, runtime
|
||||
statechart modification, multi-threaded tokio. See
|
||||
[`docs/002. hsmc-semantics-formal.md`](docs/002.%20hsmc-semantics-formal.md)
|
||||
§ "What `hsmc` deliberately does NOT have" for the rationale and
|
||||
what to use instead.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -0,0 +1,381 @@
|
||||
# `hsmc` — How Your Chart Behaves
|
||||
|
||||
**Status:** DRAFT. This is the canonical answer to "what will my statechart
|
||||
actually do?" When this document and another disagree, this one wins.
|
||||
|
||||
**Audience:** anyone writing a chart. The goal is that after reading this,
|
||||
you can predict every action call, transition, and timer fire just by
|
||||
looking at your `statechart!` block.
|
||||
|
||||
---
|
||||
|
||||
## Why `hsmc` is small (read this first)
|
||||
|
||||
`hsmc` ships the minimum set of useful statechart primitives. No guard
|
||||
conditions, no orthogonal/parallel regions, no history states, no deferred
|
||||
events, no internal transitions, no state-local context.
|
||||
|
||||
The bet is on **simple, consistent semantics**. The small surface area
|
||||
makes hsmc easy to use, easy to reason about, and easy to predict. Once
|
||||
you internalize a small set of rules, every edge case below just follows
|
||||
from them — you don't have to memorize anything new.
|
||||
|
||||
---
|
||||
|
||||
## What a chart contains
|
||||
|
||||
Each primitive, in roughly the order a developer first meets them.
|
||||
|
||||
- **State** — a named node. The root state (the machine itself) is just a
|
||||
state. Every state is just a state.
|
||||
- **Nested state** — a state inside another state. Same thing as a state.
|
||||
- **Entry action** — a function called once when a state is entered.
|
||||
- **Exit action** — a function called once when a state is exited.
|
||||
- **Transition** — exits one state and enters another, anywhere else in the
|
||||
chart. Walks from the current state up to the lowest common ancestor
|
||||
(LCA) of source and target, calling exits along the way, then walks down
|
||||
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.
|
||||
- **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
|
||||
actions. Timers and events are dispatched slightly differently — see
|
||||
the bubbling rules below.
|
||||
- **`emit()`** — pushes an event onto the machine's queue from inside an
|
||||
action. The event is dispatched after the current event has fully
|
||||
finished processing. No re-entrant dispatch.
|
||||
- **`during:` activity** — a cancellable async function. Started **after**
|
||||
the entry actions of its owning state finish; cancelled **before** the
|
||||
exit actions of that state begin to run when the state is left.
|
||||
- **`terminate`** — names an event that, when received, exits the entire
|
||||
active path bottom-up and shuts the machine down. Only valid at root.
|
||||
|
||||
---
|
||||
|
||||
## Where the machine "is"
|
||||
|
||||
At any moment, the machine is in a path of states from root down to one
|
||||
innermost state. If you're in `C` inside `B` inside `A` (which is inside
|
||||
the root), then you are simultaneously in **all** of `Root`, `A`, `B`, and
|
||||
`C`. The root is always active until the machine terminates.
|
||||
|
||||
This is the most important rule in this document. Every other rule below
|
||||
is downstream of it. **You are simultaneously in every state on the path
|
||||
from the root to the innermost active state.** If a rule somewhere else
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## How events are handled
|
||||
|
||||
Event comes in. Start at the innermost active state. Does it have a
|
||||
handler for this event? If yes, that handler runs and the event is
|
||||
consumed — no further handling.
|
||||
|
||||
If no, walk up to the parent. Repeat. If you walk all the way to the root
|
||||
and still nothing handles it, the event is silently discarded.
|
||||
|
||||
That's all. Three other things follow from this rule:
|
||||
|
||||
- A handler on a leaf state shadows a handler on its ancestor for the same
|
||||
event. The leaf wins because the search starts there.
|
||||
- If a single state has multiple handlers (actions and/or a transition)
|
||||
for the same trigger, the actions fire in declaration order, then the
|
||||
transition fires last.
|
||||
- Timer triggers do **not** bubble. A timer belongs to the state that
|
||||
declared it; it fires only in that state's scope. Events bubble; timers
|
||||
don't.
|
||||
|
||||
---
|
||||
|
||||
## How transitions work
|
||||
|
||||
The current state (for transition purposes) is the innermost active state.
|
||||
The target can be **any** state in the entire chart — there's a global
|
||||
namespace, so state names must be unique across the chart.
|
||||
|
||||
The root state is targetable too: it's named after the chart itself. So
|
||||
in `statechart! { Foo { ... } }`, an `on(Trig) => Foo;` is a valid
|
||||
transition whose target is the root. From any state inside the chart this
|
||||
is an up-transition (root is always on the active path) — exiting only
|
||||
the states strictly between current and root, with no entry actions and
|
||||
no default-descent on root. Use this when you want to wind everything
|
||||
back up to the chart's own scope.
|
||||
|
||||
To run a transition:
|
||||
|
||||
1. Find the LCA of current and target. (They might share a parent; they
|
||||
might both be on the same root-to-leaf path; the LCA is always defined
|
||||
because the root is always an upper bound.)
|
||||
2. Walk **up** from the current state, exiting each state on the way
|
||||
(cancel durings → run exit actions) until you hit the LCA. The LCA
|
||||
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.
|
||||
|
||||
The three flavors below are just three relationships between current and
|
||||
target. The same algorithm covers all of them — they only look different
|
||||
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.
|
||||
|
||||
### Transitioning to yourself
|
||||
|
||||
Self-transition: target equals the innermost active state. The standard
|
||||
transition algorithm above gives the clean answer: the LCA of the target
|
||||
with itself is its parent, so we exit only the target and re-enter only
|
||||
the target. **Nothing above the target is exited or re-entered.**
|
||||
|
||||
Concrete example. Active path is `Root → SomeState → SomeOtherState`. A
|
||||
transition fires whose target is `SomeOtherState`.
|
||||
|
||||
- Exit `SomeOtherState` (cancel durings, run exits).
|
||||
- Re-enter `SomeOtherState` (run entries, start durings).
|
||||
- `SomeState` is **never** exited, **never** re-entered, **never**
|
||||
touched. Its timers and durings keep running.
|
||||
|
||||
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.
|
||||
|
||||
Personally I don't find self-transitions all that valuable, but people
|
||||
talk about them all the time, so they're supported.
|
||||
|
||||
### Transitioning to one of your parents (the important one)
|
||||
|
||||
The case to internalize. When you transition to an ancestor of the
|
||||
current state, you exit the current state and any states between, but you
|
||||
do **not** re-enter the ancestor. You were already there.
|
||||
|
||||
- The ancestor's entry actions don't fire.
|
||||
- The ancestor's `default` is not followed.
|
||||
- The ancestor's timers don't restart.
|
||||
- The ancestor's durings keep running.
|
||||
|
||||
You cannot enter a state you never left. Spelling it out: starting from
|
||||
leaf `C` inside `B` inside `A`, a transition to `A` exits `C` then `B`,
|
||||
and now `A` is the innermost active state with no active child.
|
||||
|
||||
---
|
||||
|
||||
## Timers
|
||||
|
||||
- A timer starts when its state is entered.
|
||||
- A timer is cancelled when its state is exited.
|
||||
- Descending into a child state is **not** an exit — the parent's timers
|
||||
keep running.
|
||||
- Timers don't bubble. Only the state that declared the timer handles its
|
||||
expiry.
|
||||
- Re-entering a state restarts its timers.
|
||||
|
||||
If two timers happen to expire on the same `step()` tick — rare under
|
||||
real wall-clock timing, but possible at `step()` granularity since
|
||||
`step()` decrements all timers at once — the runtime today fires the
|
||||
*oldest* (longest-armed) timer first, because it sits earlier in the
|
||||
active-timers array. **Don't depend on this.** It's a likely outcome of
|
||||
the current implementation, not a contract. If two timers must fire in a
|
||||
specific order, model them as one timer plus an explicit `emit()` chain.
|
||||
|
||||
---
|
||||
|
||||
## Entry and exit ordering
|
||||
|
||||
Putting it all together:
|
||||
|
||||
- **Entry** runs **outer-to-inner**: when entering a path of states, the
|
||||
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.
|
||||
- **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
|
||||
actions of a state begin, that state's durings are cancelled.
|
||||
|
||||
So a full transition reads top-to-bottom as: cancel durings on the way
|
||||
out → run exits on the way out → run entries on the way in → start
|
||||
durings on the way in.
|
||||
|
||||
Observers (the journal and any active trace backend) see this as
|
||||
phase **begin** and **end** markers bracketing the work: an
|
||||
`EnterBegan { state }` fires before any of that state's entry actions /
|
||||
timer arms / during starts, and an `Entered { state }` fires after
|
||||
all of them finish. The same for `ExitBegan` / `Exited`, and
|
||||
`TransitionFired` / `TransitionComplete` bracket the whole exit-then-
|
||||
enter sequence of a transition. This is purely a visibility change —
|
||||
the operational rules above are unchanged — but it lets you tell from
|
||||
a captured trace which atoms ran inside which phase.
|
||||
|
||||
---
|
||||
|
||||
## `emit()` — sending events from inside an action
|
||||
|
||||
An action can call `self.emit(Ev)`. The event goes on the machine's
|
||||
internal queue. It is **not** processed immediately. The runtime finishes
|
||||
handling whatever event it's currently handling — including every entry
|
||||
and exit action of any transition — and only then dequeues `Ev` and
|
||||
dispatches it normally. No re-entrant dispatch.
|
||||
|
||||
Once the current handler finishes, the runtime drains anything queued
|
||||
during handling before sleeping or returning to the outer loop.
|
||||
|
||||
If the queue is full, `emit()` returns `Err(QueueFull)`. Subsequent
|
||||
actions in the same chain still run; they may attempt further emits, but
|
||||
those also fail. At end of tick, the runtime surfaces `Err(QueueFull)`
|
||||
out of `step()` / `run()` so the top-level driver can react. A queue
|
||||
overflow is a hard signal that something is wrong with sizing or with the
|
||||
producer; it is never silently swallowed.
|
||||
|
||||
---
|
||||
|
||||
## `during:` activities — async work scoped to a state
|
||||
|
||||
A `during:` is an async function that runs while its owning state is on
|
||||
the active path. It is started after the entry actions of that state
|
||||
finish, and it is cancelled before the exit actions of that state begin.
|
||||
|
||||
A during's future may be **dropped at any `.await` point** — when an
|
||||
external event arrives, when a timer fires, when another during on the
|
||||
same active path completes, or when a transition leaves the during's
|
||||
state. This is the Rust async concept of *cancellation*: the future is
|
||||
not given a chance to "finish gracefully" — it's dropped, and dropping
|
||||
runs whatever destructors `Drop` impls have, but no further `.await`s
|
||||
will ever resume.
|
||||
|
||||
The practical rule: write durings as cancel-safe state machines. Every
|
||||
`.await` must be a clean resume point where dropping the future leaves
|
||||
the borrowed fields in a re-enterable state. Don't straddle awaits with
|
||||
mutations that need to commit atomically. If you need to learn what
|
||||
cancel-safety looks like in practice, the README has the worked examples,
|
||||
and the tokio docs on cancellation are the standard reference.
|
||||
|
||||
Multiple `during:` declarations on the same active path race against each
|
||||
other (and against incoming events and timers). Each during borrows
|
||||
disjoint `&mut` slices of the context — Rust's split-borrow checker
|
||||
rejects overlapping borrows at compile time, so concurrent durings can
|
||||
never step on each other's state.
|
||||
|
||||
---
|
||||
|
||||
## Termination
|
||||
|
||||
When a `terminate` event is received, the machine exits the entire active
|
||||
path bottom-up: innermost first, then each parent, up to and including
|
||||
the root. After that, the machine is done — `is_terminated()` is true,
|
||||
`run()` returns `Ok(())`, further `step()` calls are no-ops returning
|
||||
`None`. Any pending events in the queue are dropped. Any in-flight
|
||||
durings are dropped at their next `.await`.
|
||||
|
||||
Once you adopt the simple, consistent semantics above, this just falls
|
||||
out — termination is "exit everything you're currently in, in the usual
|
||||
exit order, then stop."
|
||||
|
||||
---
|
||||
|
||||
## `step()` vs `run()` vs `dispatch()`
|
||||
|
||||
Three ways to drive the machine. Same underlying behavior; the differences
|
||||
are about who decides when to advance time.
|
||||
|
||||
- **`step(elapsed)`** — synchronous. You call it; it does at most one unit
|
||||
of work (one timer expiry, or one queued event). For bare-metal /
|
||||
testing.
|
||||
- **`dispatch(ev).await`** — async helper. Pushes `ev` onto the queue, then
|
||||
drains the queue (and any timers that come due) until quiescent. For
|
||||
injecting events from the same task that owns the machine.
|
||||
- **`run().await`** — async. Owns the task body. Races durings against the
|
||||
external event channel and timers, and processes whatever wins, in a
|
||||
loop, until termination.
|
||||
|
||||
For the same external event sequence and the same elapsed-time inputs,
|
||||
the three produce the same observable trace.
|
||||
|
||||
---
|
||||
|
||||
## What you cannot do, and why
|
||||
|
||||
The "minimum useful primitives" bet, made concrete. For each missing
|
||||
feature: why we don't have it, and what to do instead. _(First-pass
|
||||
drafts. Edit freely.)_
|
||||
|
||||
- **Guard conditions on transitions** — _Why not:_ guards bury control
|
||||
flow inside an action body, so the chart's structure stops telling you
|
||||
the whole story. _What to do instead:_ split the source into two
|
||||
states whose entry conditions differ, or have an action emit a
|
||||
follow-up event (`Ok` vs. `Bad`) and let the chart branch on that.
|
||||
- **Orthogonal / parallel regions** — _Why not:_ true parallelism
|
||||
multiplies state-space and forces a join-semantics for shared events.
|
||||
_What to do instead:_ run two charts as two tasks and connect them with
|
||||
channels, or use multiple `during:` activities for concurrent async
|
||||
work within a single state.
|
||||
- **History states (shallow or deep)** — _Why not:_ history is hidden
|
||||
mutable state — re-entering a parent goes "somewhere" based on
|
||||
invisible bookkeeping. _What to do instead:_ store the last child
|
||||
explicitly in your context, then transition directly to it on
|
||||
re-entry.
|
||||
- **Deferred events** — _Why not:_ deferring means an event you sent now
|
||||
can resurface much later, with non-obvious ordering. _What to do
|
||||
instead:_ handle the event where it arrives (even if just to log and
|
||||
drop it), or have the producer check state before sending.
|
||||
- **Internal transitions** — _Why not:_ "transition that doesn't exit or
|
||||
enter" is a separate semantics layer just to skip exit/entry. _What to
|
||||
do instead:_ declare an `action(Trig) => fn` (no transition). That's
|
||||
exactly what an internal transition is.
|
||||
- **State-local context** — _Why not:_ hierarchical context types make
|
||||
borrowing painful and tie the chart's structure into your data model.
|
||||
_What to do instead:_ put all your state in the root context;
|
||||
`during:` activities can borrow disjoint fields of it.
|
||||
- **Event priorities beyond FIFO** — _Why not:_ priorities allow
|
||||
starvation and make ordering implementation-dependent. FIFO is
|
||||
predictable. _What to do instead:_ if some events are higher-priority,
|
||||
deliver them on a separate channel into a separate, faster-cadence
|
||||
machine.
|
||||
- **Runtime statechart modification** — _Why not:_ the chart is the
|
||||
static structural definition. Mutating it at runtime defeats
|
||||
compile-time validation and makes the trace meaningless. _What to do
|
||||
instead:_ design every variation up front as states or sub-states.
|
||||
- **Inter-machine communication primitives** — _Why not:_ a built-in
|
||||
messaging layer would have to pick winners between embassy / tokio /
|
||||
bare-metal channels. _What to do instead:_ use whatever channel
|
||||
primitive your runtime gives you (embassy `Channel`, tokio `mpsc`),
|
||||
and feed events into `dispatch()` or `Sender::send()`.
|
||||
|
||||
---
|
||||
|
||||
## Quick reference
|
||||
|
||||
| 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. |
|
||||
| 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). |
|
||||
| Event handled at ancestor | Search bubbles up; first ancestor with a handler runs it. Innermost is still innermost; transition (if any) starts from innermost. |
|
||||
| Action calls `emit()` | Event queued. Dispatched after the current event's handling fully completes. |
|
||||
| Queue is full when `emit()` is called | `emit()` returns `Err(QueueFull)`. Remaining actions in the same chain still run; further emits in this tick also fail. `step()` / `run()` surfaces `QueueFull` at end of tick. |
|
||||
| `terminate` event delivered | Exit innermost → … → exit root. Pending events dropped. Durings dropped. `run()` returns `Ok(())`. |
|
||||
+735
-25
File diff suppressed because it is too large.
Load diff
@@ -26,6 +26,13 @@ pub struct Ir {
|
||||
/// Duration triggers referenced anywhere, in first-seen order.
|
||||
/// Each one gets a trigger id used by the timer table.
|
||||
pub duration_triggers: Vec<DurationTrigger>,
|
||||
/// Set when the chart declared `trace;` at root. Retained for
|
||||
/// backwards-compatible parsing — the keyword no longer gates
|
||||
/// observation emission. As of 0.4 every chart unconditionally
|
||||
/// emits `__chart_observe!` calls, and the actual trace fan-out is
|
||||
/// chosen by the user's `hsmc/trace-*` cargo feature selection.
|
||||
#[allow(dead_code)]
|
||||
pub trace_enabled: bool,
|
||||
}
|
||||
|
||||
pub struct ActionIr {
|
||||
@@ -122,6 +129,7 @@ pub fn build_ir(input: StatechartInput) -> syn::Result<Ir> {
|
||||
}
|
||||
};
|
||||
let terminate_event = root_body.terminate.as_ref().map(|(i, _)| i.clone());
|
||||
let trace_enabled = root_body.trace_enabled;
|
||||
|
||||
let mut ir = Ir {
|
||||
name,
|
||||
@@ -133,6 +141,7 @@ pub fn build_ir(input: StatechartInput) -> syn::Result<Ir> {
|
||||
actions: Vec::new(),
|
||||
event_variants: Vec::new(),
|
||||
duration_triggers: Vec::new(),
|
||||
trace_enabled,
|
||||
};
|
||||
|
||||
// Two passes: collect the set of declared state names first so
|
||||
@@ -140,6 +149,9 @@ pub fn build_ir(input: StatechartInput) -> syn::Result<Ir> {
|
||||
// (transition) or a handler fn (action) based on the declared set.
|
||||
let mut state_names = std::collections::HashSet::new();
|
||||
collect_state_names(&root_body, &mut state_names);
|
||||
// Per spec: the root state is just a state, named after the chart.
|
||||
// `on(...) => <ChartName>;` must classify as a transition to root.
|
||||
state_names.insert(ir.name.to_string());
|
||||
|
||||
let name_span = ir.name.span();
|
||||
let root_name = Ident::new("__Root", name_span);
|
||||
@@ -152,6 +164,13 @@ pub fn build_ir(input: StatechartInput) -> syn::Result<Ir> {
|
||||
);
|
||||
lower_body(&mut ir, root_id, &root_body, true, &state_names)?;
|
||||
|
||||
// Intern the terminate event variant so the journal can record it
|
||||
// by id (otherwise `__event_to_id` returns u16::MAX for the very
|
||||
// event that triggered shutdown, which is useless for replay).
|
||||
if let Some(t_ident) = ir.terminate_event.clone() {
|
||||
let _ = intern_event(&mut ir, &t_ident, None)?;
|
||||
}
|
||||
|
||||
Ok(ir)
|
||||
}
|
||||
|
||||
@@ -495,6 +514,12 @@ pub fn resolve_transitions(ir: &mut Ir) -> syn::Result<()> {
|
||||
name_map.insert(s.name.to_string(), s.id);
|
||||
}
|
||||
}
|
||||
// Per spec: the root state is targetable as a transition destination
|
||||
// by the chart's own name. Find the root (parent is None) and map
|
||||
// `<ChartName>` → root_id.
|
||||
if let Some(root) = ir.states.iter().find(|s| s.parent.is_none()) {
|
||||
name_map.insert(ir.name.to_string(), root.id);
|
||||
}
|
||||
|
||||
let n = ir.states.len();
|
||||
for i in 0..n {
|
||||
|
||||
@@ -28,6 +28,13 @@ pub struct StateBody {
|
||||
/// split borrow on the generated `select` call site; the macro emits a
|
||||
/// clearer error when it can detect overlap at expansion time.
|
||||
pub durings: Vec<During>,
|
||||
/// `trace;` — root-only flag. When set, codegen injects calls to
|
||||
/// `::hsmc::__chart_trace!(...)` at every state entry, state exit,
|
||||
/// action dispatch, and transition. The runtime backend (defmt /
|
||||
/// log / tracing / no-op) is selected by which `hsmc/trace-*` cargo
|
||||
/// feature the user enables in their `Cargo.toml`. Off by default,
|
||||
/// fully zero-cost when off.
|
||||
pub trace_enabled: bool,
|
||||
}
|
||||
|
||||
impl StateBody {
|
||||
@@ -45,6 +52,7 @@ impl StateBody {
|
||||
handlers: Vec::new(),
|
||||
children: Vec::new(),
|
||||
durings: Vec::new(),
|
||||
trace_enabled: false,
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -196,6 +204,23 @@ fn parse_body(input: ParseStream, is_root: bool) -> syn::Result<StateBody> {
|
||||
}
|
||||
body.event_ty = Some(ty);
|
||||
}
|
||||
"trace" => {
|
||||
let _: Ident = input.parse()?;
|
||||
input.parse::<Token![;]>()?;
|
||||
if !is_root {
|
||||
return Err(syn::Error::new(
|
||||
ident.span(),
|
||||
"`trace;` is only valid at root",
|
||||
));
|
||||
}
|
||||
if body.trace_enabled {
|
||||
return Err(syn::Error::new(
|
||||
ident.span(),
|
||||
"duplicate `trace;` declaration",
|
||||
));
|
||||
}
|
||||
body.trace_enabled = true;
|
||||
}
|
||||
"entry" => {
|
||||
let _: Ident = input.parse()?;
|
||||
input.parse::<Token![:]>()?;
|
||||
|
||||
@@ -25,12 +25,17 @@ pub fn validate(ir: &Ir) -> syn::Result<()> {
|
||||
// Resolve transitions: done already? We need post-build resolution.
|
||||
// We'll do it here because we need IR mutable; but we're given &Ir.
|
||||
// Instead perform target lookup inline.
|
||||
let name_map: HashMap<String, u16> = ir
|
||||
let mut name_map: HashMap<String, u16> = ir
|
||||
.states
|
||||
.iter()
|
||||
.filter(|s| s.name != "__Root")
|
||||
.map(|s| (s.name.to_string(), s.id))
|
||||
.collect();
|
||||
// Per spec: the root state is targetable as a transition destination
|
||||
// by the chart's own name.
|
||||
if let Some(root) = ir.states.iter().find(|s| s.parent.is_none()) {
|
||||
name_map.insert(ir.name.to_string(), root.id);
|
||||
}
|
||||
|
||||
for s in &ir.states {
|
||||
// Empty state (not root). A state with a `during:` is not empty —
|
||||
|
||||
@@ -3,15 +3,3 @@ error: field `a` listed twice in `during: tick(...)` — each field can only be
|
||||
|
|
||||
19 | during: tick(a, a);
|
||||
| ^
|
||||
|
||||
error[E0405]: cannot find trait `MActions` in this scope
|
||||
--> tests/ui/t10_1_during_duplicate_field.rs:26:6
|
||||
|
|
||||
26 | impl MActions for MActionContext<'_> {}
|
||||
| ^^^^^^^^ not found in this scope
|
||||
|
||||
error[E0425]: cannot find type `MActionContext` in this scope
|
||||
--> tests/ui/t10_1_during_duplicate_field.rs:26:19
|
||||
|
|
||||
26 | impl MActions for MActionContext<'_> {}
|
||||
| ^^^^^^^^^^^^^^ not found in this scope
|
||||
@@ -3,15 +3,3 @@ error: field `a` is borrowed by two concurrent durings on state `S` (`one` and `
|
||||
|
|
||||
21 | during: two(a);
|
||||
| ^
|
||||
|
||||
error[E0405]: cannot find trait `MActions` in this scope
|
||||
--> tests/ui/t10_2_during_overlap_same_state.rs:29:6
|
||||
|
|
||||
29 | impl MActions for MActionContext<'_> {}
|
||||
| ^^^^^^^^ not found in this scope
|
||||
|
||||
error[E0425]: cannot find type `MActionContext` in this scope
|
||||
--> tests/ui/t10_2_during_overlap_same_state.rs:29:19
|
||||
|
|
||||
29 | impl MActions for MActionContext<'_> {}
|
||||
| ^^^^^^^^^^^^^^ not found in this scope
|
||||
@@ -4,18 +4,6 @@ error: duplicate transition on trigger `Go` in state `Red`
|
||||
15 | on(Go) => Yellow;
|
||||
| ^^
|
||||
|
||||
error[E0405]: cannot find trait `MActions` in this scope
|
||||
--> tests/ui/t9_1_duplicate_transition.rs:22:6
|
||||
|
|
||||
22 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^ not found in this scope
|
||||
|
||||
error[E0425]: cannot find type `MActionContext` in this scope
|
||||
--> tests/ui/t9_1_duplicate_transition.rs:22:19
|
||||
|
|
||||
22 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^^^^^^^ not found in this scope
|
||||
|
||||
warning: unused import: `Duration`
|
||||
--> tests/ui/t9_1_duplicate_transition.rs:1:24
|
||||
|
|
||||
|
||||
@@ -3,15 +3,3 @@ error: state `Parent` has children but no `default` declaration
|
||||
|
|
||||
13 | state Parent {
|
||||
| ^^^^^^
|
||||
|
||||
error[E0405]: cannot find trait `MActions` in this scope
|
||||
--> tests/ui/t9_2_missing_default.rs:20:6
|
||||
|
|
||||
20 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^ not found in this scope
|
||||
|
||||
error[E0425]: cannot find type `MActionContext` in this scope
|
||||
--> tests/ui/t9_2_missing_default.rs:20:19
|
||||
|
|
||||
20 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^^^^^^^ not found in this scope
|
||||
@@ -3,15 +3,3 @@ error: `terminate` is only valid at the root level
|
||||
|
|
||||
14 | terminate(Halt);
|
||||
| ^^^^^^^^^
|
||||
|
||||
error[E0405]: cannot find trait `MActions` in this scope
|
||||
--> tests/ui/t9_3_terminate_in_child.rs:20:6
|
||||
|
|
||||
20 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^ not found in this scope
|
||||
|
||||
error[E0425]: cannot find type `MActionContext` in this scope
|
||||
--> tests/ui/t9_3_terminate_in_child.rs:20:19
|
||||
|
|
||||
20 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^^^^^^^ not found in this scope
|
||||
@@ -3,15 +3,3 @@ error: `default(Cousin)` in state `Parent`: `Cousin` is not a direct child of `P
|
||||
|
|
||||
14 | default(Cousin);
|
||||
| ^^^^^^^
|
||||
|
||||
error[E0405]: cannot find trait `MActions` in this scope
|
||||
--> tests/ui/t9_4_default_non_child.rs:21:6
|
||||
|
|
||||
21 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^ not found in this scope
|
||||
|
||||
error[E0425]: cannot find type `MActionContext` in this scope
|
||||
--> tests/ui/t9_4_default_non_child.rs:21:19
|
||||
|
|
||||
21 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^^^^^^^ not found in this scope
|
||||
@@ -3,15 +3,3 @@ error: `default` in state `Leaf` which has no child states
|
||||
|
|
||||
14 | default(Ghost);
|
||||
| ^^^^^^^
|
||||
|
||||
error[E0405]: cannot find trait `MActions` in this scope
|
||||
--> tests/ui/t9_5_default_childless.rs:20:6
|
||||
|
|
||||
20 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^ not found in this scope
|
||||
|
||||
error[E0425]: cannot find type `MActionContext` in this scope
|
||||
--> tests/ui/t9_5_default_childless.rs:20:19
|
||||
|
|
||||
20 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^^^^^^^ not found in this scope
|
||||
@@ -3,15 +3,3 @@ error: empty state `Empty`
|
||||
|
|
||||
14 | state Empty {}
|
||||
| ^^^^^
|
||||
|
||||
error[E0405]: cannot find trait `MActions` in this scope
|
||||
--> tests/ui/t9_6_empty_state.rs:18:6
|
||||
|
|
||||
18 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^ not found in this scope
|
||||
|
||||
error[E0425]: cannot find type `MActionContext` in this scope
|
||||
--> tests/ui/t9_6_empty_state.rs:18:19
|
||||
|
|
||||
18 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^^^^^^^ not found in this scope
|
||||
@@ -3,15 +3,3 @@ error: multiple `default` declarations in state `Parent`
|
||||
|
|
||||
14 | default(A);
|
||||
| ^^^^^^^
|
||||
|
||||
error[E0405]: cannot find trait `MActions` in this scope
|
||||
--> tests/ui/t9_7_duplicate_default.rs:22:6
|
||||
|
|
||||
22 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^ not found in this scope
|
||||
|
||||
error[E0425]: cannot find type `MActionContext` in this scope
|
||||
--> tests/ui/t9_7_duplicate_default.rs:22:19
|
||||
|
|
||||
22 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^^^^^^^ not found in this scope
|
||||
@@ -1,3 +1,5 @@
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::statechart;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
|
||||
@@ -1,50 +1,13 @@
|
||||
warning: unexpected `cfg` condition value: `tokio`
|
||||
--> tests/ui/t9_8_unknown_target.rs:8:1
|
||||
|
|
||||
8 | / statechart! {
|
||||
9 | | M {
|
||||
10 | | context: Ctx;
|
||||
11 | | events: Ev;
|
||||
... |
|
||||
17 | | }
|
||||
| |_^
|
||||
|
|
||||
= note: no expected values for `feature`
|
||||
= note: using a cfg inside a macro will use the cfgs from the destination crate and not the ones from the defining crate
|
||||
= help: try referring to `statechart` crate for guidance on how handle this unexpected cfg
|
||||
= help: the macro `statechart` may come from an old version of the `hsmc_macros` crate, try updating your dependency with `cargo update -p hsmc_macros`
|
||||
= note: see <https://doc.rust-lang.org/nightly/rustc/check-cfg/cargo-specifics.html> for more information about checking conditional configuration
|
||||
= note: `#[warn(unexpected_cfgs)]` on by default
|
||||
= note: this warning originates in the macro `statechart` (in Nightly builds, run with -Z macro-backtrace for more info)
|
||||
|
||||
warning: unexpected `cfg` condition value: `embassy`
|
||||
--> tests/ui/t9_8_unknown_target.rs:8:1
|
||||
|
|
||||
8 | / statechart! {
|
||||
9 | | M {
|
||||
10 | | context: Ctx;
|
||||
11 | | events: Ev;
|
||||
... |
|
||||
17 | | }
|
||||
| |_^
|
||||
|
|
||||
= note: no expected values for `feature`
|
||||
= note: using a cfg inside a macro will use the cfgs from the destination crate and not the ones from the defining crate
|
||||
= help: try referring to `statechart` crate for guidance on how handle this unexpected cfg
|
||||
= help: the macro `statechart` may come from an old version of the `hsmc_macros` crate, try updating your dependency with `cargo update -p hsmc_macros`
|
||||
= note: see <https://doc.rust-lang.org/nightly/rustc/check-cfg/cargo-specifics.html> for more information about checking conditional configuration
|
||||
= note: this warning originates in the macro `statechart` (in Nightly builds, run with -Z macro-backtrace for more info)
|
||||
|
||||
error[E0046]: not all trait items implemented, missing: `NonExistent`
|
||||
--> tests/ui/t9_8_unknown_target.rs:19:1
|
||||
--> tests/ui/t9_8_unknown_target.rs:21:1
|
||||
|
|
||||
8 | / statechart! {
|
||||
9 | | M {
|
||||
10 | | context: Ctx;
|
||||
11 | | events: Ev;
|
||||
10 | / statechart! {
|
||||
11 | | M {
|
||||
12 | | context: Ctx;
|
||||
13 | | events: Ev;
|
||||
... |
|
||||
17 | | }
|
||||
19 | | }
|
||||
| |_- `NonExistent` from trait
|
||||
18 |
|
||||
19 | impl MActions for MActionContext<'_> {}
|
||||
20 |
|
||||
21 | impl MActions for MActionContext<'_> {}
|
||||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ missing `NonExistent` in implementation
|
||||
@@ -3,15 +3,3 @@ error: multiple `terminate` declarations
|
||||
|
|
||||
13 | terminate(Halt);
|
||||
| ^^^^^^^^^
|
||||
|
||||
error[E0405]: cannot find trait `MActions` in this scope
|
||||
--> tests/ui/t9_9_multiple_terminate.rs:19:6
|
||||
|
|
||||
19 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^ not found in this scope
|
||||
|
||||
error[E0425]: cannot find type `MActionContext` in this scope
|
||||
--> tests/ui/t9_9_multiple_terminate.rs:19:19
|
||||
|
|
||||
19 | impl MActions for MActionContext<'_> {
|
||||
| ^^^^^^^^^^^^^^ not found in this scope
|
||||
+25
-1
@@ -17,14 +17,38 @@ exclude = ["examples/microwave_tui.rs"]
|
||||
default = []
|
||||
tokio = ["dep:tokio"]
|
||||
embassy = ["dep:embassy-sync", "dep:embassy-time", "dep:embassy-futures"]
|
||||
# Auto-tracing sinks — every chart emits `__chart_observe!` calls
|
||||
# unconditionally; whichever of these sinks you enable is what gets
|
||||
# textual log lines. Pick zero, one, or any combination — the
|
||||
# observation pipeline fans out to all enabled sinks and the in-memory
|
||||
# journal (below). With NO sink feature enabled, observation is fully
|
||||
# elided at compile time (zero overhead).
|
||||
#
|
||||
# Format: `[statechart:<Name>] <verb> key=value …` (logfmt-style,
|
||||
# greppable, regex-parseable). The `tracing` backend uses native
|
||||
# structured fields instead of stringly key=value pairs.
|
||||
trace-defmt = ["dep:defmt"]
|
||||
trace-log = ["dep:log"]
|
||||
trace-tracing = ["dep:tracing"]
|
||||
# In-memory journal sink. When enabled, every `__chart_observe!` site
|
||||
# also records a `TraceEvent` into the per-machine `JournalSink`. The
|
||||
# journal is the authoritative byte-deterministic atom-by-atom record
|
||||
# of chart execution; trace backends are textual renderings of the
|
||||
# same vocabulary.
|
||||
# Requires `alloc` (the journal grows dynamically). Off by default —
|
||||
# zero overhead and no `alloc` requirement when not enabled.
|
||||
journal = []
|
||||
|
||||
[dependencies]
|
||||
hsmc-macros = { path = "../hsmc-macros", version = "0.2.0" }
|
||||
hsmc-macros = { path = "../hsmc-macros", version = "0.4.0" }
|
||||
heapless = "0.8"
|
||||
tokio = { version = "1", features = ["sync", "time", "rt", "macros"], optional = true }
|
||||
embassy-sync = { version = "0.8", optional = true }
|
||||
embassy-time = { version = "0.5", optional = true }
|
||||
embassy-futures = { version = "0.1", optional = true }
|
||||
defmt = { version = "0.3", optional = true }
|
||||
log = { version = "0.4", optional = true }
|
||||
tracing = { version = "0.1", default-features = false, optional = true }
|
||||
|
||||
[target.'cfg(any(target_os = "linux", target_os = "macos", target_os = "windows"))'.dev-dependencies]
|
||||
trybuild = "1"
|
||||
|
||||
@@ -0,0 +1,156 @@
|
||||
//! Deterministic execution journal for `hsmc` charts.
|
||||
//!
|
||||
//! Behind `feature = "journal"`. The macro emits one [`TraceEvent`] for every
|
||||
//! observable atom in chart execution: entries, exits, action invocations,
|
||||
//! during start/cancel, timer arm/cancel/fire, queued emits, event delivery,
|
||||
//! transitions, and termination.
|
||||
//!
|
||||
//! For a fixed `(chart, initial context, external event sequence,
|
||||
//! elapsed-time inputs)`, the produced journal is byte-identical across runs
|
||||
//! — that's the contract the verification harness checks against.
|
||||
//!
|
||||
//! All identifiers in the journal are stable u16 indices generated at macro
|
||||
//! expansion time. Each chart also exposes:
|
||||
//!
|
||||
//! - `<Chart>::CHART_HASH: u64` — identifies the chart definition; mismatch
|
||||
//! on replay = different chart.
|
||||
//! - `<Chart>::state_name(id)`, `<Chart>::action_name(id)`,
|
||||
//! `<Chart>::event_name(id)`, `<Chart>::timer_label(id)` — human-readable
|
||||
//! names for debugging.
|
||||
//!
|
||||
//! The journal does not record `during:` race outcomes from `run()` — race
|
||||
//! winners depend on wall-clock timing and are not part of the deterministic
|
||||
//! contract (see semantics doc). What you see in the journal is the *result*
|
||||
//! of any race: the event the winning during emitted.
|
||||
|
||||
extern crate alloc;
|
||||
pub(crate) use alloc::vec::Vec;
|
||||
|
||||
/// Owned journal returned by `take_journal()`. A `Vec<TraceEvent>` whose
|
||||
/// concrete crate (`alloc::vec::Vec`) is hidden so callers don't need an
|
||||
/// `extern crate alloc` of their own.
|
||||
pub type Journal = alloc::vec::Vec<TraceEvent>;
|
||||
|
||||
/// Distinguishes which kind of slot an action was invoked in. Pure metadata
|
||||
/// — the action body is the same regardless. Lets the journal be readable
|
||||
/// without cross-referencing surrounding events.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
|
||||
pub enum ActionKind {
|
||||
/// Entry action of a state.
|
||||
Entry,
|
||||
/// Exit action of a state.
|
||||
Exit,
|
||||
/// Handler action (action attached to a transition or standalone
|
||||
/// `action(...) => fn`).
|
||||
Handler,
|
||||
}
|
||||
|
||||
/// Why a transition fired. Carried on `TransitionFired` so observers can
|
||||
/// see *what triggered* the state change, not just that one happened.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
|
||||
pub enum TransitionReason {
|
||||
/// External or queued event with the given index dispatched into a
|
||||
/// handler that fired this transition.
|
||||
Event { event: u16 },
|
||||
/// Timer on the given (state, timer) slot expired and its handler
|
||||
/// fired this transition.
|
||||
Timer { state: u16, timer: u16 },
|
||||
/// Driven from inside the runtime without an originating event or
|
||||
/// timer (e.g. default-descent into a child after entering a
|
||||
/// composite state). Reserved; not currently emitted.
|
||||
Internal,
|
||||
}
|
||||
|
||||
/// One observable atom of chart execution. The macro emits these at every
|
||||
/// hook point so the full sequence can be journaled and compared.
|
||||
///
|
||||
/// Variants carry stable u16 indices, never strings. Serialization (binary
|
||||
/// or JSON) of these values is reproducible across rebuilds.
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
|
||||
pub enum TraceEvent {
|
||||
/// First event in any journal. Identifies the chart definition.
|
||||
Started { chart_hash: u64 },
|
||||
/// A state's entry began. The marker is emitted before any of the
|
||||
/// state's entry actions, timers, or durings have run. Followed by
|
||||
/// `ActionInvoked{Entry}`, `TimerArmed`, `DuringStarted`, then the
|
||||
/// matching `Entered` end marker.
|
||||
EnterBegan { state: u16 },
|
||||
/// A state's entry completed. Emitted after every entry action,
|
||||
/// timer arm, and during start has run for that state. Pairs with
|
||||
/// the prior `EnterBegan { state }`.
|
||||
Entered { state: u16 },
|
||||
/// A state's exit began. The marker is emitted before any of the
|
||||
/// state's during cancellations, timer cancellations, or exit
|
||||
/// actions have run. Followed by `DuringCancelled`, `TimerCancelled`,
|
||||
/// `ActionInvoked{Exit}`, then the matching `Exited` end marker.
|
||||
ExitBegan { state: u16 },
|
||||
/// A state's exit completed. Emitted after every during cancel,
|
||||
/// timer cancel, and exit action has run for that state. Pairs with
|
||||
/// the prior `ExitBegan { state }`.
|
||||
Exited { state: u16 },
|
||||
/// An action function was called.
|
||||
ActionInvoked {
|
||||
state: u16,
|
||||
action: u16,
|
||||
kind: ActionKind,
|
||||
},
|
||||
/// A `during:` activity became logically active for its owning state.
|
||||
/// Index is the state-local declaration order (0-based).
|
||||
DuringStarted { state: u16, during: u16 },
|
||||
/// A `during:` activity was cancelled because its owning state is
|
||||
/// being exited.
|
||||
DuringCancelled { state: u16, during: u16 },
|
||||
/// A transition is about to fire. `from` is the innermost active
|
||||
/// state at the moment the transition was triggered; `to` is the
|
||||
/// target; `reason` records what caused the transition (event,
|
||||
/// timer, or internal). Followed by the actual `ExitBegan`/`Exited`/
|
||||
/// `EnterBegan`/`Entered` events that implement the transition,
|
||||
/// then the matching `TransitionComplete` end marker.
|
||||
TransitionFired {
|
||||
from: Option<u16>,
|
||||
to: u16,
|
||||
reason: TransitionReason,
|
||||
},
|
||||
/// A transition completed. Emitted after the transition's exit and
|
||||
/// entry sequences are fully done. Pairs with the prior
|
||||
/// `TransitionFired { from, to, .. }`.
|
||||
TransitionComplete { from: Option<u16>, to: u16 },
|
||||
/// An event was popped from the internal queue and is about to be
|
||||
/// dispatched. Emitted before the handler search; followed by either
|
||||
/// `EventDelivered` (handler found and ran) or `EventDropped`
|
||||
/// (no handler on the active path), or `TerminateRequested` if the
|
||||
/// event matches the chart's terminate declaration.
|
||||
EventReceived { event: u16 },
|
||||
/// An event reached a state's handler. `handler_state` is the state
|
||||
/// whose handler ran (which may be an ancestor of the innermost
|
||||
/// active state if the event bubbled).
|
||||
EventDelivered { handler_state: u16, event: u16 },
|
||||
/// An event was dispatched but no state on the active path had a
|
||||
/// handler. Silently dropped per spec.
|
||||
EventDropped { event: u16 },
|
||||
/// `emit()` from inside an action successfully pushed an event onto
|
||||
/// the internal queue.
|
||||
EmitQueued { event: u16 },
|
||||
/// `emit()` from inside an action failed because the queue was full.
|
||||
/// The action chain continues; the runtime surfaces `QueueFull` at
|
||||
/// end of tick.
|
||||
EmitFailed { event: u16 },
|
||||
/// An event matched the chart's `terminate(...)` declaration and is
|
||||
/// about to drive shutdown. Followed by the bottom-up exit chain
|
||||
/// (Exited events) and a final `Terminated`.
|
||||
TerminateRequested { event: u16 },
|
||||
/// A timer was armed (set to start counting down) for a state.
|
||||
/// `ns` is the duration in nanoseconds.
|
||||
TimerArmed { state: u16, timer: u16, ns: u64 },
|
||||
/// A timer was cancelled because its owning state is being exited.
|
||||
TimerCancelled { state: u16, timer: u16 },
|
||||
/// A timer's countdown reached zero and its handler is about to run.
|
||||
TimerFired { state: u16, timer: u16 },
|
||||
/// The chart processed its `terminate` event and the run loop is
|
||||
/// done. Always the final event in the journal.
|
||||
Terminated,
|
||||
}
|
||||
|
||||
// JournalSink lives in `__private` (in `lib.rs`) so the codegen can
|
||||
// unconditionally refer to `::hsmc::__private::JournalSink` whether or
|
||||
// not the `journal` feature is on.
|
||||
+661
@@ -102,6 +102,616 @@ pub use hsmc_macros::statechart;
|
||||
mod error;
|
||||
pub use error::HsmcError;
|
||||
|
||||
// ── Unified observation pipeline ────────────────────────────────────
|
||||
//
|
||||
// The `statechart!` macro emits ONE `__chart_observe!` call per
|
||||
// observable atom of execution — entry/exit phase begin/end markers,
|
||||
// action invocations, during start/cancel, timer arm/cancel/fire,
|
||||
// emit queue push/fail, event receive/deliver/drop, transition
|
||||
// begin/complete, terminate-requested, and terminated.
|
||||
//
|
||||
// `__chart_observe!` is the single dispatcher: each arm fans the
|
||||
// observation out to whichever sinks are enabled at compile time:
|
||||
//
|
||||
// - `feature = "journal"` → push a `TraceEvent` into the
|
||||
// per-machine `JournalSink`.
|
||||
// - `feature = "trace-defmt"` → emit a `defmt::*` log line.
|
||||
// - `feature = "trace-log"` → emit a `log::*` log line.
|
||||
// - `feature = "trace-tracing"` → emit a `tracing::*` event with
|
||||
// structured fields.
|
||||
//
|
||||
// With NO sink feature enabled, every arm body is empty and the
|
||||
// macro's args are never expanded — zero runtime cost, zero binary
|
||||
// growth. There is intentionally no catch-all arm: an unrecognized
|
||||
// invocation produces a compile error, so codegen mismatches are
|
||||
// caught loudly rather than silently dropped.
|
||||
//
|
||||
// Trace and journal share the same vocabulary by construction. The
|
||||
// trace's textual rendering is machine-parseable (logfmt-style:
|
||||
// `[statechart:Name] verb key=value …`), so a captured log can be
|
||||
// diff'd against expected behavior the same way the journal can.
|
||||
|
||||
#[cfg(feature = "journal")]
|
||||
mod journal;
|
||||
|
||||
#[cfg(feature = "journal")]
|
||||
pub use journal::{ActionKind, Journal, TraceEvent, TransitionReason};
|
||||
|
||||
/// Internal observation dispatcher invoked by `statechart!`-generated
|
||||
/// code. Not part of the public API.
|
||||
///
|
||||
/// Call form (one arm per `TraceEvent` variant):
|
||||
/// `__chart_observe!(<Variant>, <sink-expr>, <chart-literal>, <variant args…>)`
|
||||
///
|
||||
/// `sink-expr` is the place expression for the journal sink (typically
|
||||
/// `&mut self.__journal`); `chart-literal` is the chart name as a
|
||||
/// string literal. Variant args are passed positionally — see each arm
|
||||
/// for the order. Names (state, action, event, timer, during) are
|
||||
/// passed as `&'static str` literals at each call site so the trace
|
||||
/// formatters never do a runtime lookup.
|
||||
///
|
||||
/// All sink-feature gates apply *inside* each arm. With every sink
|
||||
/// feature off, the arm body is empty; the macro's positional args are
|
||||
/// never expanded; the call site contributes zero code.
|
||||
#[doc(hidden)]
|
||||
#[macro_export]
|
||||
macro_rules! __chart_observe {
|
||||
// ── Started ────────────────────────────────────────────────────
|
||||
(Started, $sink:expr, $chart:literal, $hash:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::Started { chart_hash: $hash });
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!(
|
||||
"[statechart:{}] started chart_hash={=u64:#x}",
|
||||
$chart,
|
||||
$hash
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!("[statechart:{}] started chart_hash={:#x}", $chart, $hash);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(chart = $chart, chart_hash = $hash, "started");
|
||||
}};
|
||||
|
||||
// ── EnterBegan / Entered ───────────────────────────────────────
|
||||
(EnterBegan, $sink:expr, $chart:literal, $sid:expr, $sname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::EnterBegan { state: $sid });
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!("[statechart:{}] entering state={}", $chart, $sname);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!("[statechart:{}] entering state={}", $chart, $sname);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(chart = $chart, state = $sname, "entering");
|
||||
}};
|
||||
(Entered, $sink:expr, $chart:literal, $sid:expr, $sname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::Entered { state: $sid });
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!("[statechart:{}] entered state={}", $chart, $sname);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!("[statechart:{}] entered state={}", $chart, $sname);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(chart = $chart, state = $sname, "entered");
|
||||
}};
|
||||
|
||||
// ── ExitBegan / Exited ─────────────────────────────────────────
|
||||
(ExitBegan, $sink:expr, $chart:literal, $sid:expr, $sname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::ExitBegan { state: $sid });
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!("[statechart:{}] exiting state={}", $chart, $sname);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!("[statechart:{}] exiting state={}", $chart, $sname);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(chart = $chart, state = $sname, "exiting");
|
||||
}};
|
||||
(Exited, $sink:expr, $chart:literal, $sid:expr, $sname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::Exited { state: $sid });
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!("[statechart:{}] exited state={}", $chart, $sname);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!("[statechart:{}] exited state={}", $chart, $sname);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(chart = $chart, state = $sname, "exited");
|
||||
}};
|
||||
|
||||
// ── ActionInvoked (Entry / Exit / Handler) ─────────────────────
|
||||
(ActionInvoked, $sink:expr, $chart:literal,
|
||||
$sid:expr, $sname:expr,
|
||||
$aid:expr, $aname:expr,
|
||||
Entry) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::ActionInvoked {
|
||||
state: $sid,
|
||||
action: $aid,
|
||||
kind: $crate::ActionKind::Entry,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::trace!(
|
||||
"[statechart:{}] action state={} action={} kind=entry",
|
||||
$chart,
|
||||
$sname,
|
||||
$aname
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::trace!(
|
||||
"[statechart:{}] action state={} action={} kind=entry",
|
||||
$chart,
|
||||
$sname,
|
||||
$aname
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::trace!(
|
||||
chart = $chart,
|
||||
state = $sname,
|
||||
action = $aname,
|
||||
kind = "entry",
|
||||
"action"
|
||||
);
|
||||
}};
|
||||
(ActionInvoked, $sink:expr, $chart:literal,
|
||||
$sid:expr, $sname:expr,
|
||||
$aid:expr, $aname:expr,
|
||||
Exit) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::ActionInvoked {
|
||||
state: $sid,
|
||||
action: $aid,
|
||||
kind: $crate::ActionKind::Exit,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::trace!(
|
||||
"[statechart:{}] action state={} action={} kind=exit",
|
||||
$chart,
|
||||
$sname,
|
||||
$aname
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::trace!(
|
||||
"[statechart:{}] action state={} action={} kind=exit",
|
||||
$chart,
|
||||
$sname,
|
||||
$aname
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::trace!(
|
||||
chart = $chart,
|
||||
state = $sname,
|
||||
action = $aname,
|
||||
kind = "exit",
|
||||
"action"
|
||||
);
|
||||
}};
|
||||
(ActionInvoked, $sink:expr, $chart:literal,
|
||||
$sid:expr, $sname:expr,
|
||||
$aid:expr, $aname:expr,
|
||||
Handler) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::ActionInvoked {
|
||||
state: $sid,
|
||||
action: $aid,
|
||||
kind: $crate::ActionKind::Handler,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::trace!(
|
||||
"[statechart:{}] action state={} action={} kind=handler",
|
||||
$chart,
|
||||
$sname,
|
||||
$aname
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::trace!(
|
||||
"[statechart:{}] action state={} action={} kind=handler",
|
||||
$chart,
|
||||
$sname,
|
||||
$aname
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::trace!(
|
||||
chart = $chart,
|
||||
state = $sname,
|
||||
action = $aname,
|
||||
kind = "handler",
|
||||
"action"
|
||||
);
|
||||
}};
|
||||
|
||||
// ── DuringStarted / DuringCancelled ────────────────────────────
|
||||
(DuringStarted, $sink:expr, $chart:literal,
|
||||
$sid:expr, $sname:expr,
|
||||
$did:expr, $dname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::DuringStarted {
|
||||
state: $sid,
|
||||
during: $did,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::debug!(
|
||||
"[statechart:{}] during-started state={} during={}",
|
||||
$chart,
|
||||
$sname,
|
||||
$dname
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::debug!(
|
||||
"[statechart:{}] during-started state={} during={}",
|
||||
$chart,
|
||||
$sname,
|
||||
$dname
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::debug!(
|
||||
chart = $chart,
|
||||
state = $sname,
|
||||
during = $dname,
|
||||
"during-started"
|
||||
);
|
||||
}};
|
||||
(DuringCancelled, $sink:expr, $chart:literal,
|
||||
$sid:expr, $sname:expr,
|
||||
$did:expr, $dname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::DuringCancelled {
|
||||
state: $sid,
|
||||
during: $did,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::debug!(
|
||||
"[statechart:{}] during-cancelled state={} during={}",
|
||||
$chart,
|
||||
$sname,
|
||||
$dname
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::debug!(
|
||||
"[statechart:{}] during-cancelled state={} during={}",
|
||||
$chart,
|
||||
$sname,
|
||||
$dname
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::debug!(
|
||||
chart = $chart,
|
||||
state = $sname,
|
||||
during = $dname,
|
||||
"during-cancelled"
|
||||
);
|
||||
}};
|
||||
|
||||
// ── TransitionFired (begin marker) ─────────────────────────────
|
||||
//
|
||||
// The reason is rendered three ways (event:Name, timer:State/Timer,
|
||||
// internal). The journal stores the structured reason and the trace
|
||||
// gets a pre-rendered `&'static str` (`$rname`) so log lines stay
|
||||
// simple to parse.
|
||||
(TransitionFired, $sink:expr, $chart:literal,
|
||||
$from:expr, $fname:expr,
|
||||
$to:expr, $tname:expr,
|
||||
$reason:expr, $rname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::TransitionFired {
|
||||
from: $from,
|
||||
to: $to,
|
||||
reason: $reason,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!(
|
||||
"[statechart:{}] transition-begin from={} to={} reason={}",
|
||||
$chart,
|
||||
$fname,
|
||||
$tname,
|
||||
$rname
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!(
|
||||
"[statechart:{}] transition-begin from={} to={} reason={}",
|
||||
$chart,
|
||||
$fname,
|
||||
$tname,
|
||||
$rname
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(
|
||||
chart = $chart,
|
||||
from = $fname,
|
||||
to = $tname,
|
||||
reason = $rname,
|
||||
"transition-begin"
|
||||
);
|
||||
}};
|
||||
|
||||
// ── TransitionComplete (end marker) ────────────────────────────
|
||||
(TransitionComplete, $sink:expr, $chart:literal,
|
||||
$from:expr, $fname:expr,
|
||||
$to:expr, $tname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::TransitionComplete {
|
||||
from: $from,
|
||||
to: $to,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!(
|
||||
"[statechart:{}] transition-complete from={} to={}",
|
||||
$chart,
|
||||
$fname,
|
||||
$tname
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!(
|
||||
"[statechart:{}] transition-complete from={} to={}",
|
||||
$chart,
|
||||
$fname,
|
||||
$tname
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(
|
||||
chart = $chart,
|
||||
from = $fname,
|
||||
to = $tname,
|
||||
"transition-complete"
|
||||
);
|
||||
}};
|
||||
|
||||
// ── Event lifecycle ────────────────────────────────────────────
|
||||
(EventReceived, $sink:expr, $chart:literal, $eid:expr, $ename:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::EventReceived { event: $eid });
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::debug!("[statechart:{}] event-received name={}", $chart, $ename);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::debug!("[statechart:{}] event-received name={}", $chart, $ename);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::debug!(chart = $chart, name = $ename, "event-received");
|
||||
}};
|
||||
(EventDelivered, $sink:expr, $chart:literal,
|
||||
$eid:expr, $ename:expr,
|
||||
$sid:expr, $sname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::EventDelivered {
|
||||
handler_state: $sid,
|
||||
event: $eid,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!(
|
||||
"[statechart:{}] event-delivered name={} handler={}",
|
||||
$chart,
|
||||
$ename,
|
||||
$sname
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!(
|
||||
"[statechart:{}] event-delivered name={} handler={}",
|
||||
$chart,
|
||||
$ename,
|
||||
$sname
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(
|
||||
chart = $chart,
|
||||
name = $ename,
|
||||
handler = $sname,
|
||||
"event-delivered"
|
||||
);
|
||||
}};
|
||||
(EventDropped, $sink:expr, $chart:literal, $eid:expr, $ename:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::EventDropped { event: $eid });
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::debug!("[statechart:{}] event-dropped name={}", $chart, $ename);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::debug!("[statechart:{}] event-dropped name={}", $chart, $ename);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::debug!(chart = $chart, name = $ename, "event-dropped");
|
||||
}};
|
||||
|
||||
// ── emit() outcomes ────────────────────────────────────────────
|
||||
(EmitQueued, $sink:expr, $chart:literal, $eid:expr, $ename:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::EmitQueued { event: $eid });
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::debug!("[statechart:{}] emit-queued event={}", $chart, $ename);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::debug!("[statechart:{}] emit-queued event={}", $chart, $ename);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::debug!(chart = $chart, event = $ename, "emit-queued");
|
||||
}};
|
||||
(EmitFailed, $sink:expr, $chart:literal, $eid:expr, $ename:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::EmitFailed { event: $eid });
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::warn!(
|
||||
"[statechart:{}] emit-failed event={} reason=queue-full",
|
||||
$chart,
|
||||
$ename
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::warn!(
|
||||
"[statechart:{}] emit-failed event={} reason=queue-full",
|
||||
$chart,
|
||||
$ename
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::warn!(
|
||||
chart = $chart,
|
||||
event = $ename,
|
||||
reason = "queue-full",
|
||||
"emit-failed"
|
||||
);
|
||||
}};
|
||||
|
||||
// ── Timer lifecycle ────────────────────────────────────────────
|
||||
(TimerArmed, $sink:expr, $chart:literal,
|
||||
$sid:expr, $sname:expr,
|
||||
$tid:expr, $tname:expr,
|
||||
$ns:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::TimerArmed {
|
||||
state: $sid,
|
||||
timer: $tid,
|
||||
ns: $ns,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::debug!(
|
||||
"[statechart:{}] timer-armed state={} timer={} duration_ns={=u64}",
|
||||
$chart,
|
||||
$sname,
|
||||
$tname,
|
||||
$ns
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::debug!(
|
||||
"[statechart:{}] timer-armed state={} timer={} duration_ns={}",
|
||||
$chart,
|
||||
$sname,
|
||||
$tname,
|
||||
$ns
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::debug!(
|
||||
chart = $chart,
|
||||
state = $sname,
|
||||
timer = $tname,
|
||||
duration_ns = $ns,
|
||||
"timer-armed"
|
||||
);
|
||||
}};
|
||||
(TimerCancelled, $sink:expr, $chart:literal,
|
||||
$sid:expr, $sname:expr,
|
||||
$tid:expr, $tname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::TimerCancelled {
|
||||
state: $sid,
|
||||
timer: $tid,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::debug!(
|
||||
"[statechart:{}] timer-cancelled state={} timer={}",
|
||||
$chart,
|
||||
$sname,
|
||||
$tname
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::debug!(
|
||||
"[statechart:{}] timer-cancelled state={} timer={}",
|
||||
$chart,
|
||||
$sname,
|
||||
$tname
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::debug!(
|
||||
chart = $chart,
|
||||
state = $sname,
|
||||
timer = $tname,
|
||||
"timer-cancelled"
|
||||
);
|
||||
}};
|
||||
(TimerFired, $sink:expr, $chart:literal,
|
||||
$sid:expr, $sname:expr,
|
||||
$tid:expr, $tname:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::TimerFired {
|
||||
state: $sid,
|
||||
timer: $tid,
|
||||
});
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!(
|
||||
"[statechart:{}] timer-fired state={} timer={}",
|
||||
$chart,
|
||||
$sname,
|
||||
$tname
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!(
|
||||
"[statechart:{}] timer-fired state={} timer={}",
|
||||
$chart,
|
||||
$sname,
|
||||
$tname
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(
|
||||
chart = $chart,
|
||||
state = $sname,
|
||||
timer = $tname,
|
||||
"timer-fired"
|
||||
);
|
||||
}};
|
||||
|
||||
// ── Termination ────────────────────────────────────────────────
|
||||
(TerminateRequested, $sink:expr, $chart:literal, $eid:expr, $ename:expr) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::TerminateRequested { event: $eid });
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!(
|
||||
"[statechart:{}] terminate-requested event={}",
|
||||
$chart,
|
||||
$ename
|
||||
);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!(
|
||||
"[statechart:{}] terminate-requested event={}",
|
||||
$chart,
|
||||
$ename
|
||||
);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(chart = $chart, event = $ename, "terminate-requested");
|
||||
}};
|
||||
(Terminated, $sink:expr, $chart:literal) => {{
|
||||
#[cfg(feature = "journal")]
|
||||
{
|
||||
$sink.push($crate::TraceEvent::Terminated);
|
||||
}
|
||||
#[cfg(feature = "trace-defmt")]
|
||||
::defmt::info!("[statechart:{}] terminated", $chart);
|
||||
#[cfg(feature = "trace-log")]
|
||||
::log::info!("[statechart:{}] terminated", $chart);
|
||||
#[cfg(feature = "trace-tracing")]
|
||||
::tracing::info!(chart = $chart, "terminated");
|
||||
}};
|
||||
}
|
||||
|
||||
#[doc(hidden)]
|
||||
pub mod __private {
|
||||
//! Implementation details used by code generated by the `statechart!` macro.
|
||||
@@ -110,6 +720,57 @@ pub mod __private {
|
||||
|
||||
pub use crate::error::HsmcError;
|
||||
|
||||
// ── JournalSink ──────────────────────────────────────────────────
|
||||
//
|
||||
// The codegen unconditionally declares a `__journal: JournalSink`
|
||||
// field on the generated machine and on the action context. When the
|
||||
// `journal` feature is on, JournalSink wraps a `Vec<TraceEvent>` and
|
||||
// the `__chart_journal!` macro pushes events into it. When off, it's
|
||||
// a ZST and the macro expands to nothing — zero overhead, no `alloc`
|
||||
// requirement.
|
||||
|
||||
/// Journal sink storing the in-order trace of observable execution
|
||||
/// atoms when `feature = "journal"` is enabled. Zero-sized when
|
||||
/// disabled.
|
||||
#[cfg(feature = "journal")]
|
||||
#[derive(Default, Debug, Clone)]
|
||||
pub struct JournalSink {
|
||||
events: crate::journal::Vec<crate::TraceEvent>,
|
||||
}
|
||||
|
||||
#[cfg(feature = "journal")]
|
||||
impl JournalSink {
|
||||
pub const fn new() -> Self {
|
||||
Self {
|
||||
events: crate::journal::Vec::new(),
|
||||
}
|
||||
}
|
||||
#[inline]
|
||||
pub fn push(&mut self, event: crate::TraceEvent) {
|
||||
self.events.push(event);
|
||||
}
|
||||
pub fn events(&self) -> &[crate::TraceEvent] {
|
||||
&self.events
|
||||
}
|
||||
pub fn take(&mut self) -> crate::journal::Vec<crate::TraceEvent> {
|
||||
core::mem::take(&mut self.events)
|
||||
}
|
||||
pub fn clear(&mut self) {
|
||||
self.events.clear();
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(not(feature = "journal"))]
|
||||
#[derive(Default, Debug, Clone, Copy)]
|
||||
pub struct JournalSink;
|
||||
|
||||
#[cfg(not(feature = "journal"))]
|
||||
impl JournalSink {
|
||||
pub const fn new() -> Self {
|
||||
Self
|
||||
}
|
||||
}
|
||||
|
||||
/// A simple bounded event queue built on `heapless::Deque`.
|
||||
/// Capacity is a const generic.
|
||||
pub struct EventQueue<E, const N: usize> {
|
||||
|
||||
@@ -0,0 +1,408 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for EVENT BUBBLING.
|
||||
//!
|
||||
//! Spec section "How events are handled":
|
||||
//! Event comes in. Start at the innermost active state. Does it have a
|
||||
//! handler for this event? If yes, that handler runs and the event is
|
||||
//! consumed — no further handling. If no, walk up to the parent. Repeat.
|
||||
//! If you walk all the way to the root and still nothing handles it, the
|
||||
//! event is silently discarded.
|
||||
//!
|
||||
//! - A handler on a leaf state shadows a handler on its ancestor.
|
||||
//! - Multiple handlers in the same state for the same trigger:
|
||||
//! actions in declaration order, then the transition.
|
||||
//! - Timer triggers do NOT bubble.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
LeafEv, // handled at leaf
|
||||
MidEv, // handled at Mid only
|
||||
RootEv, // handled at root only
|
||||
Unknown, // no handler anywhere
|
||||
Shadowed, // handler at both Leaf and Mid; leaf wins
|
||||
MultiAct, // multiple actions in same state for same trigger
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Bub {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(Mid);
|
||||
terminate(Halt);
|
||||
|
||||
on(RootEv) => root_handler;
|
||||
|
||||
state Mid {
|
||||
entry: m_in;
|
||||
exit: m_out;
|
||||
default(Leaf);
|
||||
on(MidEv) => mid_handler;
|
||||
on(Shadowed) => mid_shadowed;
|
||||
state Leaf {
|
||||
entry: l_in;
|
||||
exit: l_out;
|
||||
on(LeafEv) => leaf_handler;
|
||||
on(Shadowed) => leaf_shadowed;
|
||||
on(MultiAct) => multi1;
|
||||
on(MultiAct) => multi2;
|
||||
on(MultiAct) => multi3;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl BubActions for BubActionContext<'_> {
|
||||
async fn m_in(&mut self) {}
|
||||
async fn m_out(&mut self) {}
|
||||
async fn l_in(&mut self) {}
|
||||
async fn l_out(&mut self) {}
|
||||
async fn root_handler(&mut self) {}
|
||||
async fn mid_handler(&mut self) {}
|
||||
async fn leaf_handler(&mut self) {}
|
||||
async fn mid_shadowed(&mut self) {}
|
||||
async fn leaf_shadowed(&mut self) {}
|
||||
async fn multi1(&mut self) {}
|
||||
async fn multi2(&mut self) {}
|
||||
async fn multi3(&mut self) {}
|
||||
}
|
||||
|
||||
const SR: u16 = 0;
|
||||
const SM: u16 = 1;
|
||||
const SL: u16 = 2;
|
||||
// Action interning order:
|
||||
// Root body: handlers (root_handler → 0)
|
||||
// Mid body: m_in → 1, m_out → 2; handlers (mid_handler → 3, mid_shadowed → 4)
|
||||
// Leaf body: l_in → 5, l_out → 6; handlers (leaf_handler → 7, leaf_shadowed → 8, multi1..3 → 9..11)
|
||||
const A_ROOT_HANDLER: u16 = 0;
|
||||
const A_MID_HANDLER: u16 = 3;
|
||||
const A_LEAF_HANDLER: u16 = 7;
|
||||
const A_MID_SHADOWED: u16 = 4;
|
||||
const A_LEAF_SHADOWED: u16 = 8;
|
||||
const A_MULTI1: u16 = 9;
|
||||
const A_MULTI2: u16 = 10;
|
||||
const A_MULTI3: u16 = 11;
|
||||
// Event interning order:
|
||||
// Root processes first: handler RootEv → 0
|
||||
// Then Mid: MidEv → 1, Shadowed → 2
|
||||
// Then Leaf: LeafEv → 3, Shadowed already interned, MultiAct → 4
|
||||
const E_ROOTEV: u16 = 0;
|
||||
const E_MIDEV: u16 = 1;
|
||||
const E_SHADOWED: u16 = 2;
|
||||
const E_LEAFEV: u16 = 3;
|
||||
const E_MULTIACT: u16 = 4;
|
||||
|
||||
fn handler_act(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Handler,
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_bub_handler_at_leaf() {
|
||||
// Leaf has handler for LeafEv. Bubbling stops at Leaf.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Bub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::LeafEv).await;
|
||||
let j = m.take_journal();
|
||||
// Find the EventDelivered for LeafEv.
|
||||
let delivered = j.iter().find(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::EventDelivered {
|
||||
event: E_LEAFEV,
|
||||
..
|
||||
}
|
||||
)
|
||||
});
|
||||
assert!(
|
||||
matches!(
|
||||
delivered,
|
||||
Some(TraceEvent::EventDelivered {
|
||||
handler_state: SL,
|
||||
event: E_LEAFEV
|
||||
})
|
||||
),
|
||||
"LeafEv must be delivered to Leaf, got: {:?}",
|
||||
delivered
|
||||
);
|
||||
// The handler action must fire.
|
||||
let saw_handler = j.iter().any(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
state: SL,
|
||||
action: A_LEAF_HANDLER,
|
||||
kind: ActionKind::Handler
|
||||
}
|
||||
)
|
||||
});
|
||||
assert!(saw_handler, "leaf_handler must run");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_bub_event_bubbles_to_parent() {
|
||||
// Leaf has no handler for MidEv. Bubble to Mid.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Bub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::MidEv).await;
|
||||
let j = m.take_journal();
|
||||
let delivered = j
|
||||
.iter()
|
||||
.find(|e| matches!(e, TraceEvent::EventDelivered { event: E_MIDEV, .. }));
|
||||
assert!(
|
||||
matches!(
|
||||
delivered,
|
||||
Some(TraceEvent::EventDelivered {
|
||||
handler_state: SM,
|
||||
event: E_MIDEV
|
||||
})
|
||||
),
|
||||
"MidEv must be delivered to Mid, got: {:?}",
|
||||
delivered
|
||||
);
|
||||
assert_eq!(
|
||||
j.iter()
|
||||
.filter(|e| matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
action: A_MID_HANDLER,
|
||||
..
|
||||
}
|
||||
))
|
||||
.count(),
|
||||
1
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_bub_event_bubbles_to_root() {
|
||||
// Neither Leaf nor Mid handles RootEv. Bubble to Root.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Bub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::RootEv).await;
|
||||
let j = m.take_journal();
|
||||
let delivered = j.iter().find(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::EventDelivered {
|
||||
event: E_ROOTEV,
|
||||
..
|
||||
}
|
||||
)
|
||||
});
|
||||
assert!(
|
||||
matches!(
|
||||
delivered,
|
||||
Some(TraceEvent::EventDelivered {
|
||||
handler_state: SR,
|
||||
event: E_ROOTEV
|
||||
})
|
||||
),
|
||||
"RootEv must be delivered to Root, got: {:?}",
|
||||
delivered
|
||||
);
|
||||
assert_eq!(
|
||||
j.iter()
|
||||
.filter(|e| matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
action: A_ROOT_HANDLER,
|
||||
..
|
||||
}
|
||||
))
|
||||
.count(),
|
||||
1
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_bub_unknown_event_dropped() {
|
||||
// No state handles Unknown. Spec: "the event is silently discarded."
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Bub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Unknown).await;
|
||||
let j = m.take_journal();
|
||||
// Must contain an EventDropped for Unknown.
|
||||
let dropped = j
|
||||
.iter()
|
||||
.any(|e| matches!(e, TraceEvent::EventDropped { .. }));
|
||||
assert!(
|
||||
dropped,
|
||||
"unhandled Unknown must be journaled as EventDropped"
|
||||
);
|
||||
// No EventDelivered for it.
|
||||
let delivered_count = j
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::EventDelivered { .. }))
|
||||
.count();
|
||||
// No EventDelivered should fire at all (we only sent Unknown).
|
||||
assert_eq!(
|
||||
delivered_count, 0,
|
||||
"Unknown must not be delivered; got: {:?}",
|
||||
j
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_bub_leaf_shadows_parent() {
|
||||
// Both Leaf and Mid have handlers for Shadowed. Leaf wins (search starts there).
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Bub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Shadowed).await;
|
||||
let j = m.take_journal();
|
||||
let leaf_fired = j.iter().any(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
action: A_LEAF_SHADOWED,
|
||||
..
|
||||
}
|
||||
)
|
||||
});
|
||||
let mid_fired = j.iter().any(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
action: A_MID_SHADOWED,
|
||||
..
|
||||
}
|
||||
)
|
||||
});
|
||||
assert!(leaf_fired, "leaf_shadowed must fire (innermost wins)");
|
||||
assert!(!mid_fired, "mid_shadowed must NOT fire (shadowed by leaf)");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_bub_multiple_handlers_declaration_order() {
|
||||
// Leaf has three actions for MultiAct. They must fire in declaration order.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Bub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::MultiAct).await;
|
||||
let order: Vec<u16> = m
|
||||
.take_journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked {
|
||||
action,
|
||||
kind: ActionKind::Handler,
|
||||
..
|
||||
} => Some(*action),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(
|
||||
order,
|
||||
vec![A_MULTI1, A_MULTI2, A_MULTI3],
|
||||
"multi-action handlers must fire in declaration order"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_bub_handler_state_recorded_correctly() {
|
||||
// EventDelivered.handler_state must reflect WHERE the handler matched, not
|
||||
// where the event was sent.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Bub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::MidEv).await;
|
||||
let _ = m.dispatch(Ev::RootEv).await;
|
||||
let j = m.take_journal();
|
||||
let mid_delivered = j
|
||||
.iter()
|
||||
.find(|e| matches!(e, TraceEvent::EventDelivered { event: E_MIDEV, .. }));
|
||||
let root_delivered = j.iter().find(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::EventDelivered {
|
||||
event: E_ROOTEV,
|
||||
..
|
||||
}
|
||||
)
|
||||
});
|
||||
assert!(matches!(
|
||||
mid_delivered,
|
||||
Some(TraceEvent::EventDelivered {
|
||||
handler_state: SM,
|
||||
..
|
||||
})
|
||||
));
|
||||
assert!(matches!(
|
||||
root_delivered,
|
||||
Some(TraceEvent::EventDelivered {
|
||||
handler_state: SR,
|
||||
..
|
||||
})
|
||||
));
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_bub_multiple_unknown_events_each_dropped() {
|
||||
// Three unknowns — three EventDropped events.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Bub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Unknown).await;
|
||||
let _ = m.dispatch(Ev::Unknown).await;
|
||||
let _ = m.dispatch(Ev::Unknown).await;
|
||||
let dropped_count = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::EventDropped { .. }))
|
||||
.count();
|
||||
assert_eq!(dropped_count, 3);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_bub_byte_deterministic_under_mixed_events() {
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Bub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::LeafEv).await;
|
||||
let _ = m.dispatch(Ev::MidEv).await;
|
||||
let _ = m.dispatch(Ev::Unknown).await;
|
||||
let _ = m.dispatch(Ev::Shadowed).await;
|
||||
let _ = m.dispatch(Ev::MultiAct).await;
|
||||
let _ = m.dispatch(Ev::RootEv).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..15 {
|
||||
assert_eq!(first, run().await, "diverged on run {i}");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,94 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for `current_state()` reflecting the innermost
|
||||
//! active state at every point.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::statechart;
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
GoB,
|
||||
UpToParent,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Cur {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(Parent);
|
||||
terminate(Halt);
|
||||
|
||||
state Parent {
|
||||
entry: p_in;
|
||||
exit: p_out;
|
||||
default(A);
|
||||
state A {
|
||||
entry: a_in;
|
||||
exit: a_out;
|
||||
on(GoB) => B;
|
||||
on(UpToParent) => Parent;
|
||||
}
|
||||
state B {
|
||||
entry: b_in;
|
||||
exit: b_out;
|
||||
on(UpToParent) => Parent;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl CurActions for CurActionContext<'_> {
|
||||
async fn p_in(&mut self) {}
|
||||
async fn p_out(&mut self) {}
|
||||
async fn a_in(&mut self) {}
|
||||
async fn a_out(&mut self) {}
|
||||
async fn b_in(&mut self) {}
|
||||
async fn b_out(&mut self) {}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_current_state_initial_is_default_leaf() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Cur::new(Ctx);
|
||||
// Drive initial entry by sending an event.
|
||||
let _ = m.dispatch(Ev::GoB).await;
|
||||
// Now in B.
|
||||
assert_eq!(m.current_state(), CurState::B);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_current_state_after_lateral_transition() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Cur::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoB).await;
|
||||
assert_eq!(m.current_state(), CurState::B);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_current_state_after_up_returns_composite() {
|
||||
// Spec: current_state can return a composite if it became innermost via
|
||||
// an up-transition.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Cur::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToParent).await;
|
||||
assert_eq!(
|
||||
m.current_state(),
|
||||
CurState::Parent,
|
||||
"after up-transition, current_state returns the composite Parent"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,272 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for DEFAULT-DESCENT into composite targets.
|
||||
//!
|
||||
//! Spec section "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.
|
||||
//!
|
||||
//! Pins down: entries fire outer-to-inner, default-descent unrolls the chain,
|
||||
//! the leaf is the innermost active state at the end.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent, TransitionReason};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Go,
|
||||
Halt,
|
||||
}
|
||||
|
||||
// Hierarchy: Root → Idle, Root → Tower → L1 → L2 → L3
|
||||
statechart! {
|
||||
Desc {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(Idle);
|
||||
terminate(Halt);
|
||||
|
||||
state Idle {
|
||||
entry: idle_in;
|
||||
exit: idle_out;
|
||||
on(Go) => Tower;
|
||||
}
|
||||
state Tower {
|
||||
entry: tower_in;
|
||||
exit: tower_out;
|
||||
default(L1);
|
||||
state L1 {
|
||||
entry: l1_in;
|
||||
exit: l1_out;
|
||||
default(L2);
|
||||
state L2 {
|
||||
entry: l2_in;
|
||||
exit: l2_out;
|
||||
default(L3);
|
||||
state L3 {
|
||||
entry: l3_in;
|
||||
exit: l3_out;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl DescActions for DescActionContext<'_> {
|
||||
async fn idle_in(&mut self) {}
|
||||
async fn idle_out(&mut self) {}
|
||||
async fn tower_in(&mut self) {}
|
||||
async fn tower_out(&mut self) {}
|
||||
async fn l1_in(&mut self) {}
|
||||
async fn l1_out(&mut self) {}
|
||||
async fn l2_in(&mut self) {}
|
||||
async fn l2_out(&mut self) {}
|
||||
async fn l3_in(&mut self) {}
|
||||
async fn l3_out(&mut self) {}
|
||||
}
|
||||
|
||||
const SR: u16 = 0;
|
||||
const SI: u16 = 1;
|
||||
const ST: u16 = 2;
|
||||
const SL1: u16 = 3;
|
||||
const SL2: u16 = 4;
|
||||
const SL3: u16 = 5;
|
||||
const A_IDLE_IN: u16 = 0;
|
||||
const A_IDLE_OUT: u16 = 1;
|
||||
const A_TOWER_IN: u16 = 2;
|
||||
const A_TOWER_OUT: u16 = 3;
|
||||
const A_L1_IN: u16 = 4;
|
||||
const A_L1_OUT: u16 = 5;
|
||||
const A_L2_IN: u16 = 6;
|
||||
const A_L2_OUT: u16 = 7;
|
||||
const A_L3_IN: u16 = 8;
|
||||
const A_L3_OUT: u16 = 9;
|
||||
const E_GO: u16 = 0;
|
||||
|
||||
fn entry(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Entry,
|
||||
}
|
||||
}
|
||||
fn exit_(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Exit,
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_descent_target_with_three_default_levels() {
|
||||
// Idle → Tower: Tower has default chain L1 → L2 → L3.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Desc::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
let expected = vec![
|
||||
TraceEvent::Started {
|
||||
chart_hash: Desc::<8>::CHART_HASH,
|
||||
},
|
||||
TraceEvent::EnterBegan { state: SR },
|
||||
TraceEvent::Entered { state: SR },
|
||||
TraceEvent::EnterBegan { state: SI },
|
||||
entry(SI, A_IDLE_IN),
|
||||
TraceEvent::Entered { state: SI },
|
||||
TraceEvent::EventReceived { event: E_GO },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SI,
|
||||
event: E_GO,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SI),
|
||||
to: ST,
|
||||
reason: TransitionReason::Event { event: E_GO },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SI },
|
||||
exit_(SI, A_IDLE_OUT),
|
||||
TraceEvent::Exited { state: SI },
|
||||
TraceEvent::EnterBegan { state: ST },
|
||||
entry(ST, A_TOWER_IN),
|
||||
TraceEvent::Entered { state: ST },
|
||||
TraceEvent::EnterBegan { state: SL1 },
|
||||
entry(SL1, A_L1_IN),
|
||||
TraceEvent::Entered { state: SL1 },
|
||||
TraceEvent::EnterBegan { state: SL2 },
|
||||
entry(SL2, A_L2_IN),
|
||||
TraceEvent::Entered { state: SL2 },
|
||||
TraceEvent::EnterBegan { state: SL3 },
|
||||
entry(SL3, A_L3_IN),
|
||||
TraceEvent::Entered { state: SL3 },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SI),
|
||||
to: ST,
|
||||
},
|
||||
];
|
||||
|
||||
assert_eq!(actual, expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_descent_entries_fire_outer_to_inner() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Desc::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
// After the GO transition: order of Entered events should be Tower → L1 → L2 → L3.
|
||||
let split = m
|
||||
.journal()
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::TransitionFired { .. }))
|
||||
.unwrap();
|
||||
let entered: Vec<u16> = m.journal()[split..]
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Entered { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(entered, vec![ST, SL1, SL2, SL3]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_descent_termination_exits_full_chain() {
|
||||
// After full descent into L3, terminate exits L3 → L2 → L1 → Tower → Root.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Desc::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let exits: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Exited { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(exits, vec![SI, SL3, SL2, SL1, ST, SR]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_descent_action_kind_sequence() {
|
||||
// After GO: Tower entry kind, L1 entry, L2 entry, L3 entry. All Entry.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Desc::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let split = m
|
||||
.journal()
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::TransitionFired { .. }))
|
||||
.unwrap();
|
||||
// After the Idle exit, all subsequent ActionInvoked must be Entry kind.
|
||||
let kinds_after_exit: Vec<ActionKind> = m.journal()[split + 3..]
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked { kind, .. } => Some(*kind),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert!(
|
||||
kinds_after_exit.iter().all(|k| *k == ActionKind::Entry),
|
||||
"all post-transition actions must be Entry kind, got {:?}",
|
||||
kinds_after_exit
|
||||
);
|
||||
assert_eq!(kinds_after_exit.len(), 4, "Tower + L1 + L2 + L3 entries");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_descent_byte_deterministic() {
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Desc::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..10 {
|
||||
assert_eq!(first, run().await, "diverged on run {i}");
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_descent_initial_descent_is_idle_only() {
|
||||
// Initial default chain is Root → Idle. Idle has no children, so only one Entered.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Desc::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let entered: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Entered { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(entered, vec![SR, SI]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,252 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for `during:` activities.
|
||||
//!
|
||||
//! Spec section "during: activities":
|
||||
//! A `during:` is an async function that runs while its owning state is on
|
||||
//! the active path. It is started after the entry actions of that state
|
||||
//! finish, and it is cancelled before the exit actions of that state begin.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use core::time::Duration;
|
||||
use hsmc::{statechart, ActionKind, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx {
|
||||
pub a: u32,
|
||||
pub b: u32,
|
||||
pub c: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Done,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Du {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(Working);
|
||||
terminate(Halt);
|
||||
|
||||
state Working {
|
||||
entry: w_in;
|
||||
exit: w_out;
|
||||
during: tick_a(a);
|
||||
during: tick_b(b);
|
||||
on(Done) => Idle;
|
||||
}
|
||||
state Idle {
|
||||
entry: i_in;
|
||||
exit: i_out;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl DuActions for DuActionContext<'_> {
|
||||
async fn w_in(&mut self) {}
|
||||
async fn w_out(&mut self) {}
|
||||
async fn i_in(&mut self) {}
|
||||
async fn i_out(&mut self) {}
|
||||
}
|
||||
|
||||
async fn tick_a(_a: &mut u32) -> Ev {
|
||||
// Pause for a long time; this future will likely be cancelled before
|
||||
// completing so we exercise the cancel path.
|
||||
tokio::time::sleep(Duration::from_secs(60)).await;
|
||||
Ev::Done
|
||||
}
|
||||
|
||||
async fn tick_b(_b: &mut u32) -> Ev {
|
||||
tokio::time::sleep(Duration::from_secs(60)).await;
|
||||
Ev::Done
|
||||
}
|
||||
|
||||
const SR: u16 = 0;
|
||||
const SW: u16 = 1;
|
||||
const SI: u16 = 2;
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_during_started_after_entries() {
|
||||
// Spec: started AFTER entry actions of the owning state finish.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Du::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let j = m.take_journal();
|
||||
// Find Working's entry action invocation.
|
||||
let w_entry_idx = j.iter().position(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
state: SW,
|
||||
kind: ActionKind::Entry,
|
||||
..
|
||||
}
|
||||
)
|
||||
});
|
||||
// Find first DuringStarted on Working.
|
||||
let d_started_idx = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::DuringStarted { state: SW, .. }));
|
||||
assert!(w_entry_idx.is_some());
|
||||
assert!(d_started_idx.is_some());
|
||||
assert!(
|
||||
w_entry_idx.unwrap() < d_started_idx.unwrap(),
|
||||
"DuringStarted must come AFTER entry actions"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_during_cancelled_before_exits() {
|
||||
// Spec: cancelled BEFORE exit actions of the owning state begin.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Du::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let j = m.take_journal();
|
||||
let d_cancelled_idx = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::DuringCancelled { state: SW, .. }));
|
||||
let w_exit_idx = j.iter().position(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
state: SW,
|
||||
kind: ActionKind::Exit,
|
||||
..
|
||||
}
|
||||
)
|
||||
});
|
||||
assert!(d_cancelled_idx.is_some(), "DuringCancelled must appear");
|
||||
assert!(w_exit_idx.is_some(), "exit actions must run");
|
||||
assert!(
|
||||
d_cancelled_idx.unwrap() < w_exit_idx.unwrap(),
|
||||
"DuringCancelled must come BEFORE exit actions"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_during_two_durings_two_started_two_cancelled() {
|
||||
// Two durings declared on Working — should see two DuringStarted and two DuringCancelled.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Du::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let j = m.take_journal();
|
||||
let started = j
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::DuringStarted { state: SW, .. }))
|
||||
.count();
|
||||
let cancelled = j
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::DuringCancelled { state: SW, .. }))
|
||||
.count();
|
||||
assert_eq!(started, 2);
|
||||
assert_eq!(cancelled, 2);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_during_indices_are_declaration_order() {
|
||||
// Indices 0, 1 in declaration order.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Du::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let started_indices: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::DuringStarted { during, .. } => Some(*during),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(started_indices, vec![0, 1]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_during_cancelled_indices_match() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Du::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let cancelled_indices: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::DuringCancelled { during, .. } => Some(*during),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
// Cancellation also walks declaration order in the current implementation.
|
||||
assert_eq!(cancelled_indices, vec![0, 1]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_during_state_id_matches() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Du::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let started_states: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::DuringStarted { state, .. } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
// Both DuringStarted events refer to Working (id 1).
|
||||
assert!(started_states.iter().all(|&s| s == SW));
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_during_no_durings_on_idle() {
|
||||
// Idle has no `during:` declarations. After we transition into Idle, no
|
||||
// DuringStarted for Idle.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Du::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Done).await;
|
||||
let on_idle: usize = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::DuringStarted { state: SI, .. }))
|
||||
.count();
|
||||
assert_eq!(on_idle, 0);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_during_byte_deterministic() {
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Du::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Done).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..10 {
|
||||
assert_eq!(first, run().await, "diverged on run {i}");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,255 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for `emit()` from action code.
|
||||
//!
|
||||
//! Spec section "emit()":
|
||||
//! The event goes on the machine's internal queue. It is NOT processed
|
||||
//! immediately. The runtime finishes handling whatever event it's
|
||||
//! currently handling — including every entry and exit action of any
|
||||
//! transition — and only then dequeues `Ev` and dispatches it normally.
|
||||
//! No re-entrant dispatch.
|
||||
//!
|
||||
//! If the queue is full, `emit()` returns `Err(QueueFull)`. Subsequent
|
||||
//! actions in the same chain still run; they may attempt further emits,
|
||||
//! but those also fail.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Trigger,
|
||||
Followup,
|
||||
Many,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Em {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(A);
|
||||
terminate(Halt);
|
||||
|
||||
state A {
|
||||
entry: a_in;
|
||||
exit: a_out;
|
||||
on(Trigger) => emit_followup;
|
||||
on(Followup) => B;
|
||||
on(Many) => emit_many;
|
||||
}
|
||||
state B {
|
||||
entry: b_in;
|
||||
exit: b_out;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl EmActions for EmActionContext<'_> {
|
||||
async fn a_in(&mut self) {}
|
||||
async fn a_out(&mut self) {}
|
||||
async fn b_in(&mut self) {}
|
||||
async fn b_out(&mut self) {}
|
||||
async fn emit_followup(&mut self) {
|
||||
let _ = self.emit(Ev::Followup);
|
||||
}
|
||||
async fn emit_many(&mut self) {
|
||||
// Try to overflow the queue; capacity is 8 by default.
|
||||
for _ in 0..15 {
|
||||
let _ = self.emit(Ev::Followup);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const E_TRIGGER: u16 = 0;
|
||||
const E_FOLLOWUP: u16 = 1;
|
||||
const E_MANY: u16 = 2;
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_emit_queues_event() {
|
||||
// emit_followup queues Followup. Journal must have EmitQueued.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Em::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Trigger).await;
|
||||
let queued = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::EmitQueued { .. }))
|
||||
.count();
|
||||
assert_eq!(queued, 1, "exactly one EmitQueued, got {:?}", m.journal());
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_emit_followup_event_is_dispatched() {
|
||||
// After Trigger fires emit_followup, the queue contains Followup.
|
||||
// dispatch() drains, so Followup is dispatched and transitions A → B.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Em::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Trigger).await;
|
||||
let j = m.take_journal();
|
||||
|
||||
// Both Trigger and Followup must be EventDelivered.
|
||||
let delivered_events: Vec<u16> = j
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::EventDelivered { event, .. } => Some(*event),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(delivered_events, vec![E_TRIGGER, E_FOLLOWUP]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_emit_no_reentrant_dispatch() {
|
||||
// Spec: emit during a handler must not re-enter the dispatcher inside the
|
||||
// current handler. The emit_followup action does ONE thing: emit. Then it
|
||||
// returns. ONLY THEN does the dispatcher pick up Followup.
|
||||
//
|
||||
// Verify: the EmitQueued event for Followup appears BEFORE the
|
||||
// EventDelivered for Followup.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Em::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Trigger).await;
|
||||
let j = m.take_journal();
|
||||
let queued_idx = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::EmitQueued { event: E_FOLLOWUP }))
|
||||
.unwrap();
|
||||
let delivered_idx = j
|
||||
.iter()
|
||||
.position(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::EventDelivered {
|
||||
event: E_FOLLOWUP,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.unwrap();
|
||||
assert!(
|
||||
queued_idx < delivered_idx,
|
||||
"EmitQueued ({}) must come before EventDelivered ({})",
|
||||
queued_idx,
|
||||
delivered_idx
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_emit_overflow_records_emitfailed() {
|
||||
// emit_many tries 15 emits. Default queue cap is 8 (one slot has Many in
|
||||
// it currently being processed; 7 more fit). Some succeed, some fail.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Em::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Many).await;
|
||||
let j = m.take_journal();
|
||||
let queued = j
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::EmitQueued { .. }))
|
||||
.count();
|
||||
let failed = j
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::EmitFailed { .. }))
|
||||
.count();
|
||||
assert!(queued > 0, "some emits must succeed");
|
||||
assert!(failed > 0, "some emits must fail when queue overflows");
|
||||
assert_eq!(queued + failed, 15, "total emit attempts must be 15");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_emit_does_not_reorder_external_events() {
|
||||
// External events still process in arrival order. Emitted events are
|
||||
// appended to the queue (FIFO).
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Em::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Trigger).await;
|
||||
let j = m.take_journal();
|
||||
let delivered_events: Vec<u16> = j
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::EventDelivered { event, .. } => Some(*event),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
// Trigger was delivered first, then the emitted Followup.
|
||||
assert_eq!(delivered_events[0], E_TRIGGER);
|
||||
assert_eq!(delivered_events[1], E_FOLLOWUP);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_emit_byte_deterministic() {
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Em::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Trigger).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..10 {
|
||||
assert_eq!(first, run().await, "diverged on run {i}");
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_emit_state_after_emit_action_runs_to_completion() {
|
||||
// Spec: subsequent actions in the same chain still run after emit failure.
|
||||
// Hard to test surgically without an action-after-emit; pin instead that
|
||||
// the EmitFailed events are followed by additional ActionInvoked events
|
||||
// for the SAME emit_many handler call.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Em::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Many).await;
|
||||
let j = m.take_journal();
|
||||
// The handler emit_many is one call; it emits 15 times. So we should see
|
||||
// 15 emit-result events all between two boundaries: after Many's
|
||||
// EventDelivered and before any subsequent Followup deliveries.
|
||||
let many_delivered_idx = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::EventDelivered { event: E_MANY, .. }))
|
||||
.unwrap();
|
||||
let emit_results: Vec<&TraceEvent> = j[many_delivered_idx..]
|
||||
.iter()
|
||||
.take_while(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::EmitQueued { .. }
|
||||
| TraceEvent::EmitFailed { .. }
|
||||
| TraceEvent::ActionInvoked { .. }
|
||||
| TraceEvent::EventDelivered { event: E_MANY, .. }
|
||||
)
|
||||
})
|
||||
.filter(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::EmitQueued { .. } | TraceEvent::EmitFailed { .. }
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(emit_results.len(), 15);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,141 @@
|
||||
#![allow(dead_code)]
|
||||
//! Tests that an `emit()` from inside an entry/exit action gets queued
|
||||
//! BEFORE the transition completes, but is dispatched AFTER.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Go,
|
||||
Cleanup, // emitted from A's exit action
|
||||
Wakeup, // emitted from B's entry action
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Et {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(A);
|
||||
terminate(Halt);
|
||||
|
||||
on(Cleanup) => log_cleanup;
|
||||
on(Wakeup) => log_wakeup;
|
||||
|
||||
state A {
|
||||
entry: a_in;
|
||||
exit: emit_cleanup;
|
||||
on(Go) => B;
|
||||
}
|
||||
state B {
|
||||
entry: emit_wakeup;
|
||||
exit: b_out;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl EtActions for EtActionContext<'_> {
|
||||
async fn a_in(&mut self) {}
|
||||
async fn b_out(&mut self) {}
|
||||
async fn emit_cleanup(&mut self) {
|
||||
let _ = self.emit(Ev::Cleanup);
|
||||
}
|
||||
async fn emit_wakeup(&mut self) {
|
||||
let _ = self.emit(Ev::Wakeup);
|
||||
}
|
||||
async fn log_cleanup(&mut self) {}
|
||||
async fn log_wakeup(&mut self) {}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_emit_in_exit_action_runs_after_transition() {
|
||||
// Spec: emitted events are processed only after the current event has
|
||||
// fully finished — including all entry/exit actions.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Et::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let j = m.take_journal();
|
||||
|
||||
// Find indices of EmitQueued for Cleanup, EmitQueued for Wakeup, and
|
||||
// EventDelivered for each.
|
||||
// Event ids in interning order: Cleanup=0, Wakeup=1 (root handlers first),
|
||||
// Go=2 (A handler), Halt=3 (terminate at end of build).
|
||||
let cleanup_queued = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::EmitQueued { event: 0 }));
|
||||
let wakeup_queued = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::EmitQueued { event: 1 }));
|
||||
let cleanup_delivered = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::EventDelivered { event: 0, .. }));
|
||||
let wakeup_delivered = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::EventDelivered { event: 1, .. }));
|
||||
|
||||
assert!(cleanup_queued.is_some(), "Cleanup must be queued");
|
||||
assert!(wakeup_queued.is_some(), "Wakeup must be queued");
|
||||
assert!(cleanup_delivered.is_some(), "Cleanup must be delivered");
|
||||
assert!(wakeup_delivered.is_some(), "Wakeup must be delivered");
|
||||
|
||||
// Both emits queue BEFORE either is delivered (no re-entrant dispatch
|
||||
// inside the original Go transition).
|
||||
assert!(cleanup_queued.unwrap() < cleanup_delivered.unwrap());
|
||||
assert!(
|
||||
wakeup_queued.unwrap() < cleanup_delivered.unwrap(),
|
||||
"Wakeup queued before Cleanup delivered (transition completes first)"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_emit_in_exit_action_journals_in_order() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Et::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let j = m.take_journal();
|
||||
|
||||
// Both Cleanup and Wakeup were queued during the Go transition. They
|
||||
// are delivered AFTER. Order: Cleanup first (emitted from A's exit
|
||||
// which runs first), then Wakeup (emitted from B's entry).
|
||||
let queued_events: Vec<u16> = j
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::EmitQueued { event } => Some(*event),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(
|
||||
queued_events,
|
||||
vec![0, 1],
|
||||
"Cleanup (id 0) then Wakeup (id 1)"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_emit_in_transition_byte_deterministic() {
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Et::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..10 {
|
||||
assert_eq!(first, run().await, "diverged on run {i}");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,325 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for INITIAL ENTRY and DEFAULT DESCENT.
|
||||
//!
|
||||
//! Pins down the semantics from `docs/002. hsmc-semantics-formal.md`,
|
||||
//! section "Where the machine 'is'":
|
||||
//!
|
||||
//! At any moment, the machine is in a path of states from root down to one
|
||||
//! innermost state. ... The root is always active until the machine
|
||||
//! terminates.
|
||||
//!
|
||||
//! And from "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.
|
||||
//!
|
||||
//! Each test compares the FULL journal to a hand-built EXPECTED sequence.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Halt,
|
||||
}
|
||||
|
||||
// 4-level hierarchy: Root → A → B → C → D
|
||||
statechart! {
|
||||
Init4 {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
|
||||
default(A);
|
||||
terminate(Halt);
|
||||
|
||||
entry: r_in;
|
||||
exit: r_out;
|
||||
|
||||
state A {
|
||||
entry: a_in;
|
||||
exit: a_out;
|
||||
default(B);
|
||||
state B {
|
||||
entry: b_in;
|
||||
exit: b_out;
|
||||
default(C);
|
||||
state C {
|
||||
entry: c_in;
|
||||
exit: c_out;
|
||||
default(D);
|
||||
state D {
|
||||
entry: d_in;
|
||||
exit: d_out;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Init4Actions for Init4ActionContext<'_> {
|
||||
async fn r_in(&mut self) {}
|
||||
async fn r_out(&mut self) {}
|
||||
async fn a_in(&mut self) {}
|
||||
async fn a_out(&mut self) {}
|
||||
async fn b_in(&mut self) {}
|
||||
async fn b_out(&mut self) {}
|
||||
async fn c_in(&mut self) {}
|
||||
async fn c_out(&mut self) {}
|
||||
async fn d_in(&mut self) {}
|
||||
async fn d_out(&mut self) {}
|
||||
}
|
||||
|
||||
// State ids: 0=Root, 1=A, 2=B, 3=C, 4=D.
|
||||
const SR: u16 = 0;
|
||||
const SA: u16 = 1;
|
||||
const SB: u16 = 2;
|
||||
const SC: u16 = 3;
|
||||
const SD: u16 = 4;
|
||||
// Action ids in declaration order: 0=r_in, 1=r_out, 2=a_in, 3=a_out,
|
||||
// 4=b_in, 5=b_out, 6=c_in, 7=c_out, 8=d_in, 9=d_out.
|
||||
const A_R_IN: u16 = 0;
|
||||
const A_R_OUT: u16 = 1;
|
||||
const A_A_IN: u16 = 2;
|
||||
const A_A_OUT: u16 = 3;
|
||||
const A_B_IN: u16 = 4;
|
||||
const A_B_OUT: u16 = 5;
|
||||
const A_C_IN: u16 = 6;
|
||||
const A_C_OUT: u16 = 7;
|
||||
const A_D_IN: u16 = 8;
|
||||
const A_D_OUT: u16 = 9;
|
||||
// Halt = event 0 (interned via `terminate(Halt)`).
|
||||
const E_HALT: u16 = 0;
|
||||
|
||||
fn entry(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Entry,
|
||||
}
|
||||
}
|
||||
fn exit_(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Exit,
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_initial_descent_records_full_path() {
|
||||
// Spec: "the root is always active" + default-descent unrolls Root → A → B → C → D.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Init4::new(Ctx);
|
||||
// Push Halt to drive the chart through initial entry then termination.
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
|
||||
let actual = m.take_journal();
|
||||
let expected = vec![
|
||||
// Initial enter (driven by dispatch's prime-state branch).
|
||||
TraceEvent::Started {
|
||||
chart_hash: Init4::<8>::CHART_HASH,
|
||||
},
|
||||
TraceEvent::EnterBegan { state: SR },
|
||||
entry(SR, A_R_IN),
|
||||
TraceEvent::Entered { state: SR },
|
||||
TraceEvent::EnterBegan { state: SA },
|
||||
entry(SA, A_A_IN),
|
||||
TraceEvent::Entered { state: SA },
|
||||
TraceEvent::EnterBegan { state: SB },
|
||||
entry(SB, A_B_IN),
|
||||
TraceEvent::Entered { state: SB },
|
||||
TraceEvent::EnterBegan { state: SC },
|
||||
entry(SC, A_C_IN),
|
||||
TraceEvent::Entered { state: SC },
|
||||
TraceEvent::EnterBegan { state: SD },
|
||||
entry(SD, A_D_IN),
|
||||
TraceEvent::Entered { state: SD },
|
||||
// Halt.
|
||||
TraceEvent::EventReceived { event: E_HALT },
|
||||
TraceEvent::TerminateRequested { event: E_HALT },
|
||||
// Bottom-up exit chain.
|
||||
TraceEvent::ExitBegan { state: SD },
|
||||
exit_(SD, A_D_OUT),
|
||||
TraceEvent::Exited { state: SD },
|
||||
TraceEvent::ExitBegan { state: SC },
|
||||
exit_(SC, A_C_OUT),
|
||||
TraceEvent::Exited { state: SC },
|
||||
TraceEvent::ExitBegan { state: SB },
|
||||
exit_(SB, A_B_OUT),
|
||||
TraceEvent::Exited { state: SB },
|
||||
TraceEvent::ExitBegan { state: SA },
|
||||
exit_(SA, A_A_OUT),
|
||||
TraceEvent::Exited { state: SA },
|
||||
TraceEvent::ExitBegan { state: SR },
|
||||
exit_(SR, A_R_OUT),
|
||||
TraceEvent::Exited { state: SR },
|
||||
TraceEvent::Terminated,
|
||||
];
|
||||
|
||||
let mismatch = actual
|
||||
.iter()
|
||||
.zip(expected.iter())
|
||||
.position(|(a, e)| a != e)
|
||||
.map(|i| i.to_string())
|
||||
.unwrap_or_else(|| "<length>".to_string());
|
||||
assert_eq!(actual, expected, "first mismatch at index {mismatch}");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_started_is_first_event() {
|
||||
// Spec: every journal begins with Started carrying the chart hash.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Init4::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let j = m.journal();
|
||||
assert!(matches!(j[0], TraceEvent::Started { .. }));
|
||||
if let TraceEvent::Started { chart_hash } = j[0] {
|
||||
assert_eq!(chart_hash, Init4::<8>::CHART_HASH);
|
||||
}
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_chart_hash_nonzero() {
|
||||
// The FNV-1a fingerprint must actually have run.
|
||||
assert_ne!(Init4::<8>::CHART_HASH, 0);
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_root_state_id_is_zero() {
|
||||
// Spec: "the root state (the machine itself) is just a state". It's
|
||||
// allocated first and so gets id 0; tests below depend on this.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Init4::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
// First Entered event must be state 0.
|
||||
let first_entered = m
|
||||
.journal()
|
||||
.iter()
|
||||
.find(|e| matches!(e, TraceEvent::Entered { .. }));
|
||||
assert!(matches!(
|
||||
first_entered,
|
||||
Some(TraceEvent::Entered { state: 0 })
|
||||
));
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_entry_actions_fire_outer_to_inner() {
|
||||
// Spec: "Entry runs outer-to-inner."
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Init4::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let entered: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
kind: ActionKind::Entry,
|
||||
..
|
||||
} => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(
|
||||
entered,
|
||||
vec![SR, SA, SB, SC, SD],
|
||||
"entry actions must fire outer-to-inner across hierarchy"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_exit_actions_fire_inner_to_outer() {
|
||||
// Spec: "Exit runs inner-to-outer."
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Init4::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let exited: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
kind: ActionKind::Exit,
|
||||
..
|
||||
} => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(
|
||||
exited,
|
||||
vec![SD, SC, SB, SA, SR],
|
||||
"exit actions must fire inner-to-outer across hierarchy"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_state_ids_are_declaration_order() {
|
||||
// Spec: state ids assigned in parse order (0=root, then nested).
|
||||
// Verify by checking the order Entered events appear.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Init4::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let entered_ids: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Entered { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(entered_ids, vec![SR, SA, SB, SC, SD]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_initial_descent_byte_deterministic_across_runs() {
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Init4::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..20 {
|
||||
assert_eq!(first, run().await, "divergence on run {i}");
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_terminated_is_last_event() {
|
||||
// Spec: "Always the final event in the journal."
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Init4::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
assert!(matches!(m.journal().last(), Some(TraceEvent::Terminated)));
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,534 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for LATERAL transitions (target not on active path).
|
||||
//!
|
||||
//! Spec section "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.
|
||||
//!
|
||||
//! Also pins down that the LCA itself is **not** exited or re-entered.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent, TransitionReason};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
GoB,
|
||||
GoC,
|
||||
GoD,
|
||||
GoE,
|
||||
Halt,
|
||||
}
|
||||
|
||||
// Hierarchy:
|
||||
// Root
|
||||
// ├── Parent
|
||||
// │ ├── A (default)
|
||||
// │ └── B
|
||||
// ├── C
|
||||
// └── D
|
||||
// └── E
|
||||
statechart! {
|
||||
Lat {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(Parent);
|
||||
terminate(Halt);
|
||||
|
||||
state Parent {
|
||||
entry: p_in;
|
||||
exit: p_out;
|
||||
default(A);
|
||||
state A {
|
||||
entry: a_in;
|
||||
exit: a_out;
|
||||
on(GoB) => B;
|
||||
on(GoC) => C;
|
||||
on(GoD) => D;
|
||||
on(GoE) => E;
|
||||
}
|
||||
state B {
|
||||
entry: b_in;
|
||||
exit: b_out;
|
||||
on(GoC) => C;
|
||||
}
|
||||
}
|
||||
state C {
|
||||
entry: c_in;
|
||||
exit: c_out;
|
||||
}
|
||||
state D {
|
||||
entry: d_in;
|
||||
exit: d_out;
|
||||
default(E);
|
||||
state E {
|
||||
entry: e_in;
|
||||
exit: e_out;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl LatActions for LatActionContext<'_> {
|
||||
async fn p_in(&mut self) {}
|
||||
async fn p_out(&mut self) {}
|
||||
async fn a_in(&mut self) {}
|
||||
async fn a_out(&mut self) {}
|
||||
async fn b_in(&mut self) {}
|
||||
async fn b_out(&mut self) {}
|
||||
async fn c_in(&mut self) {}
|
||||
async fn c_out(&mut self) {}
|
||||
async fn d_in(&mut self) {}
|
||||
async fn d_out(&mut self) {}
|
||||
async fn e_in(&mut self) {}
|
||||
async fn e_out(&mut self) {}
|
||||
}
|
||||
|
||||
// State ids: 0=Root, 1=Parent, 2=A, 3=B, 4=C, 5=D, 6=E.
|
||||
const SR: u16 = 0;
|
||||
const SP: u16 = 1;
|
||||
const SA: u16 = 2;
|
||||
const SB: u16 = 3;
|
||||
const SC: u16 = 4;
|
||||
const SD: u16 = 5;
|
||||
const SE: u16 = 6;
|
||||
// Action ids in declaration order: 0=p_in, 1=p_out, 2=a_in, 3=a_out,
|
||||
// 4=b_in, 5=b_out, 6=c_in, 7=c_out, 8=d_in, 9=d_out, 10=e_in, 11=e_out.
|
||||
const A_P_IN: u16 = 0;
|
||||
const A_P_OUT: u16 = 1;
|
||||
const A_A_IN: u16 = 2;
|
||||
const A_A_OUT: u16 = 3;
|
||||
const A_B_IN: u16 = 4;
|
||||
const A_B_OUT: u16 = 5;
|
||||
const A_C_IN: u16 = 6;
|
||||
const A_C_OUT: u16 = 7;
|
||||
const A_D_IN: u16 = 8;
|
||||
const A_D_OUT: u16 = 9;
|
||||
const A_E_IN: u16 = 10;
|
||||
const A_E_OUT: u16 = 11;
|
||||
// Event ids in first-seen order: 0=GoB, 1=GoC, 2=GoD, 3=GoE, 4=Halt.
|
||||
const E_GOB: u16 = 0;
|
||||
const E_GOC: u16 = 1;
|
||||
const E_GOD: u16 = 2;
|
||||
const E_GOE: u16 = 3;
|
||||
|
||||
fn entry(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Entry,
|
||||
}
|
||||
}
|
||||
fn exit_(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Exit,
|
||||
}
|
||||
}
|
||||
#[allow(dead_code)]
|
||||
fn handler(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Handler,
|
||||
}
|
||||
}
|
||||
|
||||
// Initial descent: Root → Parent → A.
|
||||
fn initial_descent() -> Vec<TraceEvent> {
|
||||
vec![
|
||||
TraceEvent::Started {
|
||||
chart_hash: Lat::<8>::CHART_HASH,
|
||||
},
|
||||
TraceEvent::EnterBegan { state: SR },
|
||||
TraceEvent::Entered { state: SR },
|
||||
TraceEvent::EnterBegan { state: SP },
|
||||
entry(SP, A_P_IN),
|
||||
TraceEvent::Entered { state: SP },
|
||||
TraceEvent::EnterBegan { state: SA },
|
||||
entry(SA, A_A_IN),
|
||||
TraceEvent::Entered { state: SA },
|
||||
]
|
||||
}
|
||||
|
||||
// Compare actual vs expected and report first mismatch.
|
||||
fn assert_journal(actual: &[TraceEvent], expected: &[TraceEvent]) {
|
||||
let mismatch = actual.iter().zip(expected.iter()).position(|(a, e)| a != e);
|
||||
if let Some(i) = mismatch {
|
||||
panic!(
|
||||
"journal mismatch at index {}\n actual: {:?}\n expected: {:?}\n full actual: {:#?}",
|
||||
i, actual[i], expected[i], actual
|
||||
);
|
||||
}
|
||||
assert_eq!(
|
||||
actual.len(),
|
||||
expected.len(),
|
||||
"journal length mismatch: actual {} vs expected {}\n full actual: {:#?}",
|
||||
actual.len(),
|
||||
expected.len(),
|
||||
actual
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_lateral_a_to_b_lca_is_parent() {
|
||||
// Spec: A → B (siblings under Parent). LCA = Parent. Parent is not exited
|
||||
// or re-entered.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Lat::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoB).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
let mut expected = initial_descent();
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_GOB },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SA,
|
||||
event: E_GOB,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SA),
|
||||
to: SB,
|
||||
reason: TransitionReason::Event { event: E_GOB },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SA },
|
||||
exit_(SA, A_A_OUT),
|
||||
TraceEvent::Exited { state: SA },
|
||||
TraceEvent::EnterBegan { state: SB },
|
||||
entry(SB, A_B_IN),
|
||||
TraceEvent::Entered { state: SB },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SA),
|
||||
to: SB,
|
||||
},
|
||||
]);
|
||||
assert_journal(&actual, &expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_lateral_a_to_c_exits_parent() {
|
||||
// A → C: A is inside Parent, C is sibling of Parent. LCA = Root.
|
||||
// Exit A, exit Parent. Enter C.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Lat::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoC).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
let mut expected = initial_descent();
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_GOC },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SA,
|
||||
event: E_GOC,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SA),
|
||||
to: SC,
|
||||
reason: TransitionReason::Event { event: E_GOC },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SA },
|
||||
exit_(SA, A_A_OUT),
|
||||
TraceEvent::Exited { state: SA },
|
||||
TraceEvent::ExitBegan { state: SP },
|
||||
exit_(SP, A_P_OUT),
|
||||
TraceEvent::Exited { state: SP },
|
||||
TraceEvent::EnterBegan { state: SC },
|
||||
entry(SC, A_C_IN),
|
||||
TraceEvent::Entered { state: SC },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SA),
|
||||
to: SC,
|
||||
},
|
||||
]);
|
||||
assert_journal(&actual, &expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_lateral_target_with_children_default_descends() {
|
||||
// A → D: D has child E (default). After entering D, default-descend to E.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Lat::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoD).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
let mut expected = initial_descent();
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_GOD },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SA,
|
||||
event: E_GOD,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SA),
|
||||
to: SD,
|
||||
reason: TransitionReason::Event { event: E_GOD },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SA },
|
||||
exit_(SA, A_A_OUT),
|
||||
TraceEvent::Exited { state: SA },
|
||||
TraceEvent::ExitBegan { state: SP },
|
||||
exit_(SP, A_P_OUT),
|
||||
TraceEvent::Exited { state: SP },
|
||||
TraceEvent::EnterBegan { state: SD },
|
||||
entry(SD, A_D_IN),
|
||||
TraceEvent::Entered { state: SD },
|
||||
TraceEvent::EnterBegan { state: SE },
|
||||
entry(SE, A_E_IN),
|
||||
TraceEvent::Entered { state: SE },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SA),
|
||||
to: SD,
|
||||
},
|
||||
]);
|
||||
assert_journal(&actual, &expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_lateral_to_deeply_nested_target() {
|
||||
// A → E (E is the leaf of D's default chain). The target itself is the leaf
|
||||
// so default-descent doesn't add another level — but D is entered along the way.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Lat::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoE).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
let mut expected = initial_descent();
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_GOE },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SA,
|
||||
event: E_GOE,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SA),
|
||||
to: SE,
|
||||
reason: TransitionReason::Event { event: E_GOE },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SA },
|
||||
exit_(SA, A_A_OUT),
|
||||
TraceEvent::Exited { state: SA },
|
||||
TraceEvent::ExitBegan { state: SP },
|
||||
exit_(SP, A_P_OUT),
|
||||
TraceEvent::Exited { state: SP },
|
||||
TraceEvent::EnterBegan { state: SD },
|
||||
entry(SD, A_D_IN),
|
||||
TraceEvent::Entered { state: SD },
|
||||
TraceEvent::EnterBegan { state: SE },
|
||||
entry(SE, A_E_IN),
|
||||
TraceEvent::Entered { state: SE },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SA),
|
||||
to: SE,
|
||||
},
|
||||
]);
|
||||
assert_journal(&actual, &expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_lateral_chained_transitions() {
|
||||
// A → B → C: two consecutive transitions. Each independently records its
|
||||
// exits and entries.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Lat::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoB).await;
|
||||
let _ = m.dispatch(Ev::GoC).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
let mut expected = initial_descent();
|
||||
// A → B
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_GOB },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SA,
|
||||
event: E_GOB,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SA),
|
||||
to: SB,
|
||||
reason: TransitionReason::Event { event: E_GOB },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SA },
|
||||
exit_(SA, A_A_OUT),
|
||||
TraceEvent::Exited { state: SA },
|
||||
TraceEvent::EnterBegan { state: SB },
|
||||
entry(SB, A_B_IN),
|
||||
TraceEvent::Entered { state: SB },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SA),
|
||||
to: SB,
|
||||
},
|
||||
]);
|
||||
// B → C (LCA = Root, so Parent exits too).
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_GOC },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SB,
|
||||
event: E_GOC,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SB),
|
||||
to: SC,
|
||||
reason: TransitionReason::Event { event: E_GOC },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SB },
|
||||
exit_(SB, A_B_OUT),
|
||||
TraceEvent::Exited { state: SB },
|
||||
TraceEvent::ExitBegan { state: SP },
|
||||
exit_(SP, A_P_OUT),
|
||||
TraceEvent::Exited { state: SP },
|
||||
TraceEvent::EnterBegan { state: SC },
|
||||
entry(SC, A_C_IN),
|
||||
TraceEvent::Entered { state: SC },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SB),
|
||||
to: SC,
|
||||
},
|
||||
]);
|
||||
assert_journal(&actual, &expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_lateral_lca_stays_active() {
|
||||
// A → B: Parent (the LCA) must NOT appear in any Exited or Entered event.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Lat::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoB).await;
|
||||
let j = m.take_journal();
|
||||
// After initial Entered(Parent), Parent must not appear again.
|
||||
let initial_p_idx = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::Entered { state: SP }))
|
||||
.unwrap();
|
||||
let parent_events: Vec<&TraceEvent> = j
|
||||
.iter()
|
||||
.skip(initial_p_idx + 1)
|
||||
.filter(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::Entered { state: SP } | TraceEvent::Exited { state: SP }
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
assert!(
|
||||
parent_events.is_empty(),
|
||||
"LCA Parent must not be re-entered or exited; got: {:?}",
|
||||
parent_events
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_lateral_exit_inner_then_outer() {
|
||||
// A → C: exit A first (deeper), then Parent (outer).
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Lat::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoC).await;
|
||||
let exits: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Exited { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
// First exit must be A (deeper), then Parent (outer).
|
||||
assert_eq!(&exits[..2], &[SA, SP], "exits must be inner-to-outer");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_lateral_entry_outer_then_inner() {
|
||||
// A → D where D has child E: enter D first, then E.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Lat::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoD).await;
|
||||
let entries: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.skip_while(|e| !matches!(e, TraceEvent::TransitionFired { .. }))
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Entered { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(
|
||||
&entries,
|
||||
&[SD, SE],
|
||||
"entries on the way down must be outer-to-inner"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_lateral_no_default_when_target_is_leaf() {
|
||||
// A → C where C is a leaf: no default-descent, journal stops at C.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Lat::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoC).await;
|
||||
let last_entered: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Entered { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
// Initial: Root, Parent, A. After GoC: C. No further entries.
|
||||
assert_eq!(last_entered, vec![SR, SP, SA, SC]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_lateral_event_delivered_records_handler_state() {
|
||||
// The handler for GoB lives on A. EventDelivered.handler_state = A.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Lat::new(Ctx);
|
||||
let _ = m.dispatch(Ev::GoB).await;
|
||||
let delivered = m
|
||||
.journal()
|
||||
.iter()
|
||||
.find(|e| matches!(e, TraceEvent::EventDelivered { event: E_GOB, .. }));
|
||||
assert!(
|
||||
matches!(
|
||||
delivered,
|
||||
Some(TraceEvent::EventDelivered {
|
||||
handler_state: SA,
|
||||
event: E_GOB
|
||||
})
|
||||
),
|
||||
"got: {:?}",
|
||||
delivered
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,322 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for ENTRY/EXIT ORDERING (declaration order, depth order).
|
||||
//!
|
||||
//! Spec section "Entry and exit ordering":
|
||||
//! Entry runs outer-to-inner. Within a single state, entry actions fire in
|
||||
//! declaration order. Exit runs inner-to-outer. Within a single state, exit
|
||||
//! actions fire in declaration order.
|
||||
//!
|
||||
//! Spec: "If a single state has multiple handlers (actions and/or a transition)
|
||||
//! for the same trigger, the actions fire in declaration order, then the
|
||||
//! transition fires last."
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Go,
|
||||
Multi,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Ord {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(A);
|
||||
terminate(Halt);
|
||||
|
||||
entry: r1, r2, r3;
|
||||
exit: r_x1, r_x2;
|
||||
|
||||
state A {
|
||||
entry: a1, a2;
|
||||
exit: a_x1, a_x2, a_x3;
|
||||
on(Go) => B;
|
||||
on(Multi) => act1;
|
||||
on(Multi) => act2;
|
||||
on(Multi) => act3;
|
||||
on(Multi) => B;
|
||||
}
|
||||
state B {
|
||||
entry: b1;
|
||||
exit: b_x1;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl OrdActions for OrdActionContext<'_> {
|
||||
async fn r1(&mut self) {}
|
||||
async fn r2(&mut self) {}
|
||||
async fn r3(&mut self) {}
|
||||
async fn r_x1(&mut self) {}
|
||||
async fn r_x2(&mut self) {}
|
||||
async fn a1(&mut self) {}
|
||||
async fn a2(&mut self) {}
|
||||
async fn a_x1(&mut self) {}
|
||||
async fn a_x2(&mut self) {}
|
||||
async fn a_x3(&mut self) {}
|
||||
async fn b1(&mut self) {}
|
||||
async fn b_x1(&mut self) {}
|
||||
async fn act1(&mut self) {}
|
||||
async fn act2(&mut self) {}
|
||||
async fn act3(&mut self) {}
|
||||
}
|
||||
|
||||
const SR: u16 = 0;
|
||||
const SA: u16 = 1;
|
||||
const SB: u16 = 2;
|
||||
|
||||
// Action interning order from declaration:
|
||||
// Root: r1=0, r2=1, r3=2 (entries), r_x1=3, r_x2=4 (exits)
|
||||
// A: a1=5, a2=6, a_x1=7, a_x2=8, a_x3=9, then handlers act1=10, act2=11, act3=12
|
||||
// B: b1=13, b_x1=14
|
||||
const A_R1: u16 = 0;
|
||||
const A_R2: u16 = 1;
|
||||
const A_R3: u16 = 2;
|
||||
const A_RX1: u16 = 3;
|
||||
const A_RX2: u16 = 4;
|
||||
const A_A1: u16 = 5;
|
||||
const A_A2: u16 = 6;
|
||||
const A_AX1: u16 = 7;
|
||||
const A_AX2: u16 = 8;
|
||||
const A_AX3: u16 = 9;
|
||||
const A_ACT1: u16 = 10;
|
||||
const A_ACT2: u16 = 11;
|
||||
const A_ACT3: u16 = 12;
|
||||
const A_B1: u16 = 13;
|
||||
const A_BX1: u16 = 14;
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_ord_root_entries_in_declaration_order() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Ord::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
// Filter to root entry actions in journal order.
|
||||
let r_entries: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked {
|
||||
state: SR,
|
||||
action,
|
||||
kind: ActionKind::Entry,
|
||||
} => Some(*action),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(r_entries, vec![A_R1, A_R2, A_R3]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_ord_root_exits_in_declaration_order() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Ord::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let r_exits: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked {
|
||||
state: SR,
|
||||
action,
|
||||
kind: ActionKind::Exit,
|
||||
} => Some(*action),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(r_exits, vec![A_RX1, A_RX2]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_ord_state_a_entries_in_declaration_order() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Ord::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let a_entries: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked {
|
||||
state: SA,
|
||||
action,
|
||||
kind: ActionKind::Entry,
|
||||
} => Some(*action),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(a_entries, vec![A_A1, A_A2]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_ord_state_a_exits_in_declaration_order() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Ord::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let a_exits: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked {
|
||||
state: SA,
|
||||
action,
|
||||
kind: ActionKind::Exit,
|
||||
} => Some(*action),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(a_exits, vec![A_AX1, A_AX2, A_AX3]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_ord_entry_outer_then_inner_across_hierarchy() {
|
||||
// Initial entry: Root → A. Root's entries fire first, then A's.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Ord::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let entries_in_order: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.take_while(|e| !matches!(e, TraceEvent::TerminateRequested { .. }))
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked {
|
||||
action,
|
||||
kind: ActionKind::Entry,
|
||||
..
|
||||
} => Some(*action),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(entries_in_order, vec![A_R1, A_R2, A_R3, A_A1, A_A2]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_ord_exit_inner_then_outer_across_hierarchy() {
|
||||
// On terminate: A's exits then Root's exits.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Ord::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let exits_in_order: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked {
|
||||
action,
|
||||
kind: ActionKind::Exit,
|
||||
..
|
||||
} => Some(*action),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(exits_in_order, vec![A_AX1, A_AX2, A_AX3, A_RX1, A_RX2]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_ord_actions_then_transition_on_same_trigger() {
|
||||
// Multi: act1, act2, act3 fire in declaration order, then transition to B.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Ord::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Multi).await;
|
||||
let j = m.take_journal();
|
||||
|
||||
// Find the action invocations and the TransitionFired in order.
|
||||
let after_delivered: Vec<&TraceEvent> = j
|
||||
.iter()
|
||||
.skip_while(|e| !matches!(e, TraceEvent::EventDelivered { event: 1, .. }))
|
||||
// Multi is the second event: Go=0, Multi=1.
|
||||
.skip(1)
|
||||
.take(20)
|
||||
.collect();
|
||||
// First three should be Handler actions in order act1, act2, act3.
|
||||
let handler_actions: Vec<u16> = after_delivered
|
||||
.iter()
|
||||
.take_while(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
kind: ActionKind::Handler,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked { action, .. } => Some(*action),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(
|
||||
handler_actions,
|
||||
vec![A_ACT1, A_ACT2, A_ACT3],
|
||||
"actions in declaration order"
|
||||
);
|
||||
// After the actions, a TransitionFired must follow.
|
||||
let trans_idx = after_delivered
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::TransitionFired { .. }))
|
||||
.unwrap();
|
||||
assert_eq!(trans_idx, 3, "transition fires after the 3 actions");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_ord_full_transition_canonical_sequence() {
|
||||
// Spec: cancel durings → run exits inner→outer → run entries outer→inner → start durings.
|
||||
// No durings here, so just exits inner→outer + entries outer→inner.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Ord::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let j = m.take_journal();
|
||||
// Find the TransitionFired and capture everything until A's exit and B's entry are done.
|
||||
let trans_idx = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::TransitionFired { .. }))
|
||||
.unwrap();
|
||||
let kinds: Vec<ActionKind> = j[trans_idx..]
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked { kind, .. } => Some(*kind),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
// First A's exit kinds (inner-to-outer order — A is innermost), then B's entry kinds.
|
||||
let exit_count = kinds.iter().filter(|k| **k == ActionKind::Exit).count();
|
||||
let entry_count = kinds.iter().filter(|k| **k == ActionKind::Entry).count();
|
||||
assert_eq!(exit_count, 3, "A has 3 exit actions");
|
||||
assert_eq!(entry_count, 1, "B has 1 entry action");
|
||||
// Exits before entries.
|
||||
let first_entry = kinds.iter().position(|k| *k == ActionKind::Entry).unwrap();
|
||||
let last_exit = kinds.iter().rposition(|k| *k == ActionKind::Exit).unwrap();
|
||||
assert!(
|
||||
last_exit < first_entry,
|
||||
"all exits must precede all entries in a transition"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,193 @@
|
||||
#![allow(dead_code)]
|
||||
//! Pins down that the ROOT state is targetable by the chart's own name.
|
||||
//!
|
||||
//! Spec section "What a chart contains":
|
||||
//! State — a named node. The root state (the machine itself) is just a
|
||||
//! state. Every state is just a state.
|
||||
//!
|
||||
//! Spec section "How transitions work":
|
||||
//! The target can be any state in the entire chart. ... state names must
|
||||
//! be unique across the chart.
|
||||
//!
|
||||
//! From these two together: `on(Trig) => <ChartName>;` is a valid transition
|
||||
//! whose target is the root. From a leaf, this is an up-transition; from any
|
||||
//! state inside the chart it's an up-transition (root is always on the active
|
||||
//! path) — exiting only the states strictly between current and root.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent, TransitionReason};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
UpToRoot,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Sub {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(A);
|
||||
terminate(Halt);
|
||||
|
||||
entry: r_in;
|
||||
exit: r_out;
|
||||
|
||||
state A {
|
||||
entry: a_in;
|
||||
exit: a_out;
|
||||
default(B);
|
||||
state B {
|
||||
entry: b_in;
|
||||
exit: b_out;
|
||||
on(UpToRoot) => Sub; // ← target is the chart name = root
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl SubActions for SubActionContext<'_> {
|
||||
async fn r_in(&mut self) {}
|
||||
async fn r_out(&mut self) {}
|
||||
async fn a_in(&mut self) {}
|
||||
async fn a_out(&mut self) {}
|
||||
async fn b_in(&mut self) {}
|
||||
async fn b_out(&mut self) {}
|
||||
}
|
||||
|
||||
const SR: u16 = 0;
|
||||
const SA: u16 = 1;
|
||||
const SB: u16 = 2;
|
||||
const A_R_IN: u16 = 0;
|
||||
const A_R_OUT: u16 = 1;
|
||||
const A_A_IN: u16 = 2;
|
||||
const A_A_OUT: u16 = 3;
|
||||
const A_B_IN: u16 = 4;
|
||||
const A_B_OUT: u16 = 5;
|
||||
const E_UPTOROOT: u16 = 0;
|
||||
|
||||
fn entry(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Entry,
|
||||
}
|
||||
}
|
||||
fn exit_(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Exit,
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_root_targetable_by_chart_name() {
|
||||
// Chart compiles. Targeting root by chart name resolves correctly.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Sub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToRoot).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
// Up-transition to root from B: exit B and A. Root is target,
|
||||
// not exited, not re-entered, no default-descent.
|
||||
let expected = vec![
|
||||
TraceEvent::Started {
|
||||
chart_hash: Sub::<8>::CHART_HASH,
|
||||
},
|
||||
TraceEvent::EnterBegan { state: SR },
|
||||
entry(SR, A_R_IN),
|
||||
TraceEvent::Entered { state: SR },
|
||||
TraceEvent::EnterBegan { state: SA },
|
||||
entry(SA, A_A_IN),
|
||||
TraceEvent::Entered { state: SA },
|
||||
TraceEvent::EnterBegan { state: SB },
|
||||
entry(SB, A_B_IN),
|
||||
TraceEvent::Entered { state: SB },
|
||||
TraceEvent::EventReceived { event: E_UPTOROOT },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SB,
|
||||
event: E_UPTOROOT,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SB),
|
||||
to: SR,
|
||||
reason: TransitionReason::Event { event: E_UPTOROOT },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SB },
|
||||
exit_(SB, A_B_OUT),
|
||||
TraceEvent::Exited { state: SB },
|
||||
TraceEvent::ExitBegan { state: SA },
|
||||
exit_(SA, A_A_OUT),
|
||||
TraceEvent::Exited { state: SA },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SB),
|
||||
to: SR,
|
||||
},
|
||||
];
|
||||
|
||||
assert_eq!(
|
||||
actual, expected,
|
||||
"root targetable; up-transition to root exits A and B only"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_root_target_does_not_re_enter_root() {
|
||||
// After the up-to-root, root must NOT have re-entered.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Sub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToRoot).await;
|
||||
let j = m.take_journal();
|
||||
// After the TransitionFired, no Entered event should fire.
|
||||
let split = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::TransitionFired { .. }))
|
||||
.unwrap();
|
||||
let entered_after = j[split..]
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::Entered { .. }))
|
||||
.count();
|
||||
assert_eq!(
|
||||
entered_after, 0,
|
||||
"up-to-root must not re-enter root or default-descend"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_root_target_then_terminate() {
|
||||
// After up-to-root, root is the innermost active state. Terminate exits root only.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Sub::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToRoot).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let j = m.take_journal();
|
||||
// After UpToRoot we're in root only. Halt exits root only.
|
||||
let exits: Vec<u16> = j
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Exited { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(
|
||||
exits,
|
||||
vec![SB, SA, SR],
|
||||
"up-to-root exits B, A; terminate exits root"
|
||||
);
|
||||
assert!(matches!(j.last(), Some(TraceEvent::Terminated)));
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,342 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for SELF-TRANSITIONS.
|
||||
//!
|
||||
//! Spec section "Transitioning to yourself":
|
||||
//! The standard transition algorithm gives the clean answer: the LCA of the
|
||||
//! target with itself is its parent, so we exit only the target and re-enter
|
||||
//! only the target. Nothing above the target is exited or re-entered.
|
||||
//!
|
||||
//! Concrete example given in spec: in `Root → SomeState → SomeOtherState`,
|
||||
//! a transition (Trig) => SomeOtherState exits and re-enters ONLY
|
||||
//! SomeOtherState; SomeState is never touched.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent, TransitionReason};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
SelfLeaf,
|
||||
SelfMid,
|
||||
Halt,
|
||||
}
|
||||
|
||||
// Hierarchy: Root → Mid → Leaf
|
||||
// Self-transitions: SelfLeaf targets Leaf; SelfMid targets Mid.
|
||||
statechart! {
|
||||
Self_ {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(Mid);
|
||||
terminate(Halt);
|
||||
|
||||
state Mid {
|
||||
entry: m_in;
|
||||
exit: m_out;
|
||||
default(Leaf);
|
||||
on(SelfMid) => Mid;
|
||||
state Leaf {
|
||||
entry: l_in;
|
||||
exit: l_out;
|
||||
on(SelfLeaf) => Leaf;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Self_Actions for Self_ActionContext<'_> {
|
||||
async fn m_in(&mut self) {}
|
||||
async fn m_out(&mut self) {}
|
||||
async fn l_in(&mut self) {}
|
||||
async fn l_out(&mut self) {}
|
||||
}
|
||||
|
||||
const SR: u16 = 0;
|
||||
const SM: u16 = 1;
|
||||
const SL: u16 = 2;
|
||||
const A_M_IN: u16 = 0;
|
||||
const A_M_OUT: u16 = 1;
|
||||
const A_L_IN: u16 = 2;
|
||||
const A_L_OUT: u16 = 3;
|
||||
// Event interning order: handlers on the parent (Mid) are processed before
|
||||
// recursing into children (Leaf), so SelfMid is interned first.
|
||||
const E_SELFMID: u16 = 0;
|
||||
const E_SELFLEAF: u16 = 1;
|
||||
|
||||
fn entry(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Entry,
|
||||
}
|
||||
}
|
||||
fn exit_(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Exit,
|
||||
}
|
||||
}
|
||||
fn initial_descent() -> Vec<TraceEvent> {
|
||||
vec![
|
||||
TraceEvent::Started {
|
||||
chart_hash: Self_::<8>::CHART_HASH,
|
||||
},
|
||||
TraceEvent::EnterBegan { state: SR },
|
||||
TraceEvent::Entered { state: SR },
|
||||
TraceEvent::EnterBegan { state: SM },
|
||||
entry(SM, A_M_IN),
|
||||
TraceEvent::Entered { state: SM },
|
||||
TraceEvent::EnterBegan { state: SL },
|
||||
entry(SL, A_L_IN),
|
||||
TraceEvent::Entered { state: SL },
|
||||
]
|
||||
}
|
||||
fn assert_journal(actual: &[TraceEvent], expected: &[TraceEvent]) {
|
||||
let mismatch = actual.iter().zip(expected.iter()).position(|(a, e)| a != e);
|
||||
if let Some(i) = mismatch {
|
||||
panic!(
|
||||
"mismatch at index {}\n actual: {:?}\n expected: {:?}",
|
||||
i,
|
||||
actual.get(i),
|
||||
expected.get(i)
|
||||
);
|
||||
}
|
||||
assert_eq!(
|
||||
actual.len(),
|
||||
expected.len(),
|
||||
"length mismatch: actual {} vs expected {}",
|
||||
actual.len(),
|
||||
expected.len()
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_self_leaf_exits_and_reenters_only_leaf() {
|
||||
// Spec: nothing above the target is touched.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Self_::new(Ctx);
|
||||
let _ = m.dispatch(Ev::SelfLeaf).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
let mut expected = initial_descent();
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_SELFLEAF },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SL,
|
||||
event: E_SELFLEAF,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SL),
|
||||
to: SL,
|
||||
reason: TransitionReason::Event { event: E_SELFLEAF },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SL },
|
||||
exit_(SL, A_L_OUT),
|
||||
TraceEvent::Exited { state: SL },
|
||||
TraceEvent::EnterBegan { state: SL },
|
||||
entry(SL, A_L_IN),
|
||||
TraceEvent::Entered { state: SL },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SL),
|
||||
to: SL,
|
||||
},
|
||||
]);
|
||||
assert_journal(&actual, &expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_self_leaf_does_not_touch_parent() {
|
||||
// The key spec example. Mid must NOT appear in any Exited or Entered
|
||||
// event after the initial descent.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Self_::new(Ctx);
|
||||
let _ = m.dispatch(Ev::SelfLeaf).await;
|
||||
let j = m.take_journal();
|
||||
|
||||
// Find the index of the EventDelivered for SelfLeaf — everything
|
||||
// after that is the self-transition body.
|
||||
let split = j
|
||||
.iter()
|
||||
.position(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::EventDelivered {
|
||||
event: E_SELFLEAF,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.unwrap();
|
||||
|
||||
let parent_after = j[split..]
|
||||
.iter()
|
||||
.filter(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::Entered { state: SM } | TraceEvent::Exited { state: SM }
|
||||
)
|
||||
})
|
||||
.count();
|
||||
assert_eq!(parent_after, 0,
|
||||
"Mid must not be exited or re-entered during self-transition on Leaf; got tail: {:?}",
|
||||
&j[split..]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_self_composite_default_descends() {
|
||||
// Spec: "If the target happens to be a composite ... the same default-child
|
||||
// rule still applies on re-entry: exit the composite, re-enter it, then
|
||||
// descend through its default chain to a leaf."
|
||||
//
|
||||
// Currently in Mid via Leaf default. SelfMid bubbles from Leaf to Mid (Mid
|
||||
// has the handler). At dispatch time, innermost is Leaf, so Mid is not
|
||||
// the innermost — that makes it an UP-then-self situation. Actually the
|
||||
// transition algorithm classifies it: target=Mid, current=Leaf, target IS
|
||||
// on the active path and target ≠ I, so this is an UP-transition not a
|
||||
// self-transition. Let's verify what the journal records.
|
||||
//
|
||||
// (See det_up.rs for explicit up-transition tests; this test pins the
|
||||
// bubbling behavior when the handler is on Mid but the transition is to
|
||||
// Mid itself from Leaf.)
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Self_::new(Ctx);
|
||||
let _ = m.dispatch(Ev::SelfMid).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
// Per spec rules: target=Mid is ON the active path (Root→Mid→Leaf),
|
||||
// and target ≠ Leaf. So it's an UP-transition: only Leaf exits.
|
||||
// Mid's entry actions don't fire. No default-descent.
|
||||
let mut expected = initial_descent();
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_SELFMID },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SM,
|
||||
event: E_SELFMID,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SL),
|
||||
to: SM,
|
||||
reason: TransitionReason::Event { event: E_SELFMID },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SL },
|
||||
exit_(SL, A_L_OUT),
|
||||
TraceEvent::Exited { state: SL },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SL),
|
||||
to: SM,
|
||||
},
|
||||
]);
|
||||
assert_journal(&actual, &expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_self_leaf_repeated_is_deterministic() {
|
||||
// Multiple self-transitions: each independently records the same pattern.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Self_::new(Ctx);
|
||||
let _ = m.dispatch(Ev::SelfLeaf).await;
|
||||
let _ = m.dispatch(Ev::SelfLeaf).await;
|
||||
let _ = m.dispatch(Ev::SelfLeaf).await;
|
||||
let j = m.take_journal();
|
||||
// Three EventDelivered for SelfLeaf, three TransitionFired, three of each
|
||||
// exit/entry pair.
|
||||
let delivered = j
|
||||
.iter()
|
||||
.filter(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::EventDelivered {
|
||||
event: E_SELFLEAF,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.count();
|
||||
assert_eq!(delivered, 3);
|
||||
let trans = j
|
||||
.iter()
|
||||
.filter(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SL),
|
||||
to: SL,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.count();
|
||||
assert_eq!(trans, 3);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_self_byte_deterministic_across_runs() {
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Self_::new(Ctx);
|
||||
let _ = m.dispatch(Ev::SelfLeaf).await;
|
||||
let _ = m.dispatch(Ev::SelfLeaf).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..10 {
|
||||
assert_eq!(first, run().await, "run {i} diverged");
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_self_action_kinds_are_exit_then_entry() {
|
||||
// Spec: "cancel durings, run exits, run entries, start durings".
|
||||
// No durings on this chart, so we expect: Exit kind action, then Entry kind action.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Self_::new(Ctx);
|
||||
let _ = m.dispatch(Ev::SelfLeaf).await;
|
||||
let j = m.take_journal();
|
||||
let split = j
|
||||
.iter()
|
||||
.position(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::EventDelivered {
|
||||
event: E_SELFLEAF,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.unwrap();
|
||||
let kinds_after: Vec<ActionKind> = j[split..]
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked { kind, .. } => Some(*kind),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(
|
||||
kinds_after,
|
||||
vec![ActionKind::Exit, ActionKind::Entry],
|
||||
"self-transition: exit before entry"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,181 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for SELF-TRANSITION on a composite (re-enters with default-descend).
|
||||
//!
|
||||
//! Spec section "Transitioning to yourself":
|
||||
//! 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 to a leaf.
|
||||
//!
|
||||
//! To get a composite as the innermost active state, this chart uses:
|
||||
//! 1. UpToParent (D → Parent) → Parent is now innermost composite.
|
||||
//! 2. SelfMid (Parent → Parent) → exit Parent, re-enter Parent, default-descend.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
UpToParent, // D → Parent (up-transition)
|
||||
SelfParent, // Parent → Parent (self-transition on composite)
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Sc {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(Parent);
|
||||
terminate(Halt);
|
||||
|
||||
state Parent {
|
||||
entry: p_in;
|
||||
exit: p_out;
|
||||
default(Child);
|
||||
on(SelfParent) => Parent;
|
||||
state Child {
|
||||
entry: c_in;
|
||||
exit: c_out;
|
||||
default(Leaf);
|
||||
state Leaf {
|
||||
entry: l_in;
|
||||
exit: l_out;
|
||||
on(UpToParent) => Parent;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl ScActions for ScActionContext<'_> {
|
||||
async fn p_in(&mut self) {}
|
||||
async fn p_out(&mut self) {}
|
||||
async fn c_in(&mut self) {}
|
||||
async fn c_out(&mut self) {}
|
||||
async fn l_in(&mut self) {}
|
||||
async fn l_out(&mut self) {}
|
||||
}
|
||||
|
||||
const SR: u16 = 0;
|
||||
const SP: u16 = 1;
|
||||
const SC: u16 = 2;
|
||||
const SL: u16 = 3;
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_self_composite_default_descends_after_re_entry() {
|
||||
// Path: initial → Leaf. UpToParent → Parent (up). SelfParent → exit Parent,
|
||||
// re-enter Parent, default-descend (Parent → Child → Leaf).
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Sc::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToParent).await;
|
||||
let _ = m.dispatch(Ev::SelfParent).await;
|
||||
let j = m.take_journal();
|
||||
|
||||
// After SelfParent, expect: exit Parent → re-enter Parent → enter Child → enter Leaf.
|
||||
let self_idx = j
|
||||
.iter()
|
||||
.rposition(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SP),
|
||||
to: SP,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.unwrap();
|
||||
let after = &j[self_idx..];
|
||||
|
||||
let exits: Vec<u16> = after
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Exited { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
let entered: Vec<u16> = after
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Entered { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
|
||||
assert_eq!(exits, vec![SP], "self-transition exits target only");
|
||||
assert_eq!(
|
||||
entered,
|
||||
vec![SP, SC, SL],
|
||||
"re-enter target then default-descend"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_self_composite_action_kinds_in_order() {
|
||||
// After the SelfParent transition: Exit p_out, Entry p_in, Entry c_in, Entry l_in.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Sc::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToParent).await;
|
||||
let _ = m.dispatch(Ev::SelfParent).await;
|
||||
let j = m.take_journal();
|
||||
let self_idx = j
|
||||
.iter()
|
||||
.rposition(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SP),
|
||||
to: SP,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.unwrap();
|
||||
let kinds: Vec<ActionKind> = j[self_idx..]
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked { kind, .. } => Some(*kind),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(
|
||||
kinds,
|
||||
vec![
|
||||
ActionKind::Exit,
|
||||
ActionKind::Entry,
|
||||
ActionKind::Entry,
|
||||
ActionKind::Entry
|
||||
],
|
||||
"exit Parent, then enter Parent, Child, Leaf"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_self_composite_byte_deterministic() {
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Sc::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToParent).await;
|
||||
let _ = m.dispatch(Ev::SelfParent).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..10 {
|
||||
assert_eq!(first, run().await, "diverged on run {i}");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,147 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for `step()` vs `dispatch()` equivalence.
|
||||
//!
|
||||
//! Spec section "step() vs run() vs dispatch()":
|
||||
//! For the same external event sequence and the same elapsed-time inputs,
|
||||
//! the three produce the same observable trace.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Tick,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Eq {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(A);
|
||||
terminate(Halt);
|
||||
|
||||
state A {
|
||||
entry: a_in;
|
||||
exit: a_out;
|
||||
on(Tick) => B;
|
||||
}
|
||||
state B {
|
||||
entry: b_in;
|
||||
exit: b_out;
|
||||
on(Tick) => A;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl EqActions for EqActionContext<'_> {
|
||||
async fn a_in(&mut self) {}
|
||||
async fn a_out(&mut self) {}
|
||||
async fn b_in(&mut self) {}
|
||||
async fn b_out(&mut self) {}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_dispatch_drains_to_quiescence() {
|
||||
// dispatch(ev) processes ev plus any events emitted while handling ev.
|
||||
// After the await returns, the queue is empty.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Eq::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Tick).await;
|
||||
assert!(!m.has_pending_events());
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_step_and_dispatch_produce_same_journal() {
|
||||
// Drive one machine via dispatch, another via send + step until queue empty.
|
||||
// The journals must match.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
// Path 1: dispatch.
|
||||
let mut m1 = Eq::new(Ctx);
|
||||
let _ = m1.dispatch(Ev::Tick).await;
|
||||
let _ = m1.dispatch(Ev::Tick).await;
|
||||
let _ = m1.dispatch(Ev::Halt).await;
|
||||
let j_dispatch = m1.take_journal();
|
||||
|
||||
// Path 2: send + step.
|
||||
let mut m2 = Eq::new(Ctx);
|
||||
m2.send(Ev::Tick).unwrap();
|
||||
m2.send(Ev::Tick).unwrap();
|
||||
m2.send(Ev::Halt).unwrap();
|
||||
// Drive to quiescence with explicit steps.
|
||||
for _ in 0..20 {
|
||||
let _ = m2.step(::hsmc::Duration::ZERO).await;
|
||||
if m2.is_terminated() {
|
||||
break;
|
||||
}
|
||||
}
|
||||
let j_step = m2.take_journal();
|
||||
|
||||
assert_eq!(
|
||||
j_dispatch, j_step,
|
||||
"step and dispatch must produce identical journals for the same event sequence"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_step_is_at_most_one_unit_of_work() {
|
||||
// Each step() processes at most one event or one timer.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Eq::new(Ctx);
|
||||
m.send(Ev::Tick).unwrap();
|
||||
m.send(Ev::Tick).unwrap();
|
||||
m.send(Ev::Halt).unwrap();
|
||||
|
||||
// After the first step (initial enter): chart enters root → A.
|
||||
let _ = m.step(::hsmc::Duration::ZERO).await;
|
||||
// After the second step: process Tick #1 (A → B).
|
||||
let len_after_2 = {
|
||||
let _ = m.step(::hsmc::Duration::ZERO).await;
|
||||
m.journal().len()
|
||||
};
|
||||
// After the third step: process Tick #2 (B → A).
|
||||
let _ = m.step(::hsmc::Duration::ZERO).await;
|
||||
let len_after_3 = m.journal().len();
|
||||
|
||||
assert!(
|
||||
len_after_3 > len_after_2,
|
||||
"step processes additional events"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_step_repeated_idempotent_when_queue_empty() {
|
||||
// Once initial-enter is done and queue is empty, additional steps
|
||||
// (with elapsed=ZERO) are no-ops.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Eq::new(Ctx);
|
||||
let _ = m.step(::hsmc::Duration::ZERO).await; // initial entry
|
||||
let len_after_first = m.journal().len();
|
||||
for _ in 0..10 {
|
||||
let _ = m.step(::hsmc::Duration::ZERO).await;
|
||||
}
|
||||
// After the first step, no events are pending, so additional
|
||||
// step(ZERO) calls do nothing.
|
||||
assert_eq!(
|
||||
m.journal().len(),
|
||||
len_after_first,
|
||||
"step(ZERO) on empty queue must not change journal"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,219 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for TERMINATION.
|
||||
//!
|
||||
//! Spec section "Termination":
|
||||
//! When a `terminate` event is received, the machine exits the entire active
|
||||
//! path bottom-up: innermost first, then each parent, up to and including
|
||||
//! the root. After that, the machine is done — `is_terminated()` is true,
|
||||
//! `run()` returns `Ok(())`, further `step()` calls are no-ops returning
|
||||
//! `None`. Any pending events in the queue are dropped. Any in-flight
|
||||
//! durings are dropped at their next `.await`.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, HsmcError, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Halt,
|
||||
Other,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Term {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(Mid);
|
||||
terminate(Halt);
|
||||
|
||||
entry: r_in;
|
||||
exit: r_out;
|
||||
|
||||
state Mid {
|
||||
entry: m_in;
|
||||
exit: m_out;
|
||||
default(Leaf);
|
||||
on(Other) => log_other;
|
||||
state Leaf {
|
||||
entry: l_in;
|
||||
exit: l_out;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl TermActions for TermActionContext<'_> {
|
||||
async fn r_in(&mut self) {}
|
||||
async fn r_out(&mut self) {}
|
||||
async fn m_in(&mut self) {}
|
||||
async fn m_out(&mut self) {}
|
||||
async fn l_in(&mut self) {}
|
||||
async fn l_out(&mut self) {}
|
||||
async fn log_other(&mut self) {}
|
||||
}
|
||||
|
||||
const SR: u16 = 0;
|
||||
const SM: u16 = 1;
|
||||
const SL: u16 = 2;
|
||||
// Halt is interned via terminate(Halt). Other is used in `on(Other)` first.
|
||||
// IR build order: handlers processed first per body. Mid has on(Other) → 0.
|
||||
// Then Halt is interned at the end of build_ir → 1.
|
||||
const E_OTHER: u16 = 0;
|
||||
const E_HALT: u16 = 1;
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_terminate_records_terminate_requested() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Term::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let j = m.take_journal();
|
||||
// TerminateRequested fires before the bottom-up exits.
|
||||
let req_idx = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::TerminateRequested { event: E_HALT }));
|
||||
assert!(
|
||||
req_idx.is_some(),
|
||||
"TerminateRequested must appear, got: {:?}",
|
||||
j
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_terminate_exits_bottom_up() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Term::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let exits: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Exited { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(exits, vec![SL, SM, SR], "termination exits inner-to-outer");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_terminate_terminated_is_last() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Term::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
assert!(matches!(m.journal().last(), Some(TraceEvent::Terminated)));
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_terminate_dispatch_after_returns_already_terminated() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Term::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let res = m.dispatch(Ev::Other).await;
|
||||
assert!(
|
||||
matches!(res, Err(HsmcError::AlreadyTerminated)),
|
||||
"dispatch after terminate must return AlreadyTerminated, got {:?}",
|
||||
res
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_terminate_journal_unchanged_by_post_term_dispatch() {
|
||||
// Calling dispatch after terminate must not journal anything new.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Term::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let len_before = m.journal().len();
|
||||
let _ = m.dispatch(Ev::Other).await;
|
||||
let len_after = m.journal().len();
|
||||
assert_eq!(
|
||||
len_before, len_after,
|
||||
"journal length must not change after termination"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_terminate_exit_actions_run_in_order() {
|
||||
// Spec: exit actions inner-to-outer.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Term::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let exit_actions: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
kind: ActionKind::Exit,
|
||||
..
|
||||
} => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(exit_actions, vec![SL, SM, SR]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_terminate_other_event_processed_before_halt() {
|
||||
// Other is dispatched first, then Halt. Other is delivered, then Halt
|
||||
// triggers termination. EventDelivered for Other appears, but no
|
||||
// EventDelivered for Halt — instead, TerminateRequested.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Term::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Other).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let j = m.take_journal();
|
||||
let other_delivered = j
|
||||
.iter()
|
||||
.any(|e| matches!(e, TraceEvent::EventDelivered { event: E_OTHER, .. }));
|
||||
let halt_delivered = j
|
||||
.iter()
|
||||
.any(|e| matches!(e, TraceEvent::EventDelivered { event: E_HALT, .. }));
|
||||
let halt_requested = j
|
||||
.iter()
|
||||
.any(|e| matches!(e, TraceEvent::TerminateRequested { event: E_HALT }));
|
||||
assert!(other_delivered, "Other must be delivered");
|
||||
assert!(!halt_delivered, "Halt does not go through EventDelivered");
|
||||
assert!(halt_requested, "Halt goes through TerminateRequested");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_terminate_byte_deterministic() {
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Term::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Other).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..10 {
|
||||
assert_eq!(first, run().await, "diverged on run {i}");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,301 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for TIMERS.
|
||||
//!
|
||||
//! Spec section "Timers":
|
||||
//! - A timer starts when its state is entered.
|
||||
//! - A timer is cancelled when its state is exited.
|
||||
//! - Descending into a child state is not an exit — parent's timers keep running.
|
||||
//! - Timers don't bubble. Only the declaring state handles its expiry.
|
||||
//! - Re-entering a state restarts its timers.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use core::time::Duration;
|
||||
use hsmc::{statechart, ActionKind, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Stop,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Tim {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(Counting);
|
||||
terminate(Halt);
|
||||
|
||||
state Counting {
|
||||
entry: c_in;
|
||||
exit: c_out;
|
||||
on(after Duration::from_millis(50)) => Done;
|
||||
on(Stop) => Done;
|
||||
}
|
||||
state Done {
|
||||
entry: d_in;
|
||||
on(after Duration::from_millis(20)) => log_tick;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl TimActions for TimActionContext<'_> {
|
||||
async fn c_in(&mut self) {}
|
||||
async fn c_out(&mut self) {}
|
||||
async fn d_in(&mut self) {}
|
||||
async fn log_tick(&mut self) {}
|
||||
}
|
||||
|
||||
const SR: u16 = 0;
|
||||
const SC: u16 = 1;
|
||||
const SD: u16 = 2;
|
||||
// Timer ids in first-seen order: 50ms (counting) → 0, 20ms (done) → 1.
|
||||
const T_COUNTING: u16 = 0;
|
||||
const T_DONE: u16 = 1;
|
||||
|
||||
fn timer_events(j: &[TraceEvent]) -> Vec<&TraceEvent> {
|
||||
j.iter()
|
||||
.filter(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::TimerArmed { .. }
|
||||
| TraceEvent::TimerCancelled { .. }
|
||||
| TraceEvent::TimerFired { .. }
|
||||
)
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_timer_arms_on_entry() {
|
||||
// Spec: timer starts when its state is entered.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Tim::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Stop).await;
|
||||
let j = m.take_journal();
|
||||
// First TimerArmed must be Counting's 50ms timer.
|
||||
let first_armed = j
|
||||
.iter()
|
||||
.find(|e| matches!(e, TraceEvent::TimerArmed { .. }));
|
||||
assert!(
|
||||
matches!(
|
||||
first_armed,
|
||||
Some(TraceEvent::TimerArmed {
|
||||
state: SC,
|
||||
timer: T_COUNTING,
|
||||
ns: 50_000_000
|
||||
})
|
||||
),
|
||||
"got: {:?}",
|
||||
first_armed
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_timer_cancels_on_exit() {
|
||||
// Spec: timer is cancelled when its state is exited.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Tim::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Stop).await;
|
||||
let j = m.take_journal();
|
||||
// Stop transitions Counting → Done. Exit Counting must cancel its timer.
|
||||
let cancelled = j.iter().find(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::TimerCancelled {
|
||||
state: SC,
|
||||
timer: T_COUNTING
|
||||
}
|
||||
)
|
||||
});
|
||||
assert!(
|
||||
cancelled.is_some(),
|
||||
"Counting's timer must be cancelled on exit, got: {:?}",
|
||||
j
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_timer_cancel_appears_before_exit_actions() {
|
||||
// Spec: "1. cancel durings 2. cancel timers 3. exit actions 4. Exited"
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Tim::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Stop).await;
|
||||
let j = m.take_journal();
|
||||
let cancel_idx = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::TimerCancelled { state: SC, .. }))
|
||||
.unwrap();
|
||||
let exit_action_idx = j
|
||||
.iter()
|
||||
.position(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
state: SC,
|
||||
kind: ActionKind::Exit,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.unwrap();
|
||||
assert!(
|
||||
cancel_idx < exit_action_idx,
|
||||
"TimerCancelled at {} must precede ActionInvoked Exit at {}",
|
||||
cancel_idx,
|
||||
exit_action_idx
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_timer_arm_appears_after_entry_actions() {
|
||||
// The TimerArmed must come AFTER the entry action invocation.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Tim::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Stop).await;
|
||||
let j = m.take_journal();
|
||||
// First Entry-kind action on Counting:
|
||||
let entry_idx = j
|
||||
.iter()
|
||||
.position(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
state: SC,
|
||||
kind: ActionKind::Entry,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.unwrap();
|
||||
// First TimerArmed for Counting:
|
||||
let armed_idx = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::TimerArmed { state: SC, .. }))
|
||||
.unwrap();
|
||||
assert!(
|
||||
entry_idx < armed_idx,
|
||||
"entry actions ({}) must fire before TimerArmed ({})",
|
||||
entry_idx,
|
||||
armed_idx
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_timer_arm_each_state_in_path() {
|
||||
// Initial descent into Counting arms Counting's timer.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Tim::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let armed: Vec<&TraceEvent> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::TimerArmed { .. }))
|
||||
.collect();
|
||||
// Only Counting has a timer in initial descent (Done is unreached).
|
||||
assert_eq!(
|
||||
armed.len(),
|
||||
1,
|
||||
"expected 1 TimerArmed during initial descent, got {:?}",
|
||||
armed
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_timer_two_lifecycles_arm_then_cancel_each() {
|
||||
// GoChild then UpToCounting (no such event — use Stop for full exit).
|
||||
// Just check Stop's full sequence: arm → cancel.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Tim::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Stop).await;
|
||||
let evs = timer_events(m.journal());
|
||||
assert_eq!(
|
||||
evs.len(),
|
||||
3,
|
||||
"expected arm → cancel → arm (Done's timer), got {:?}",
|
||||
evs
|
||||
);
|
||||
assert!(matches!(
|
||||
evs[0],
|
||||
TraceEvent::TimerArmed {
|
||||
state: SC,
|
||||
timer: T_COUNTING,
|
||||
ns: 50_000_000
|
||||
}
|
||||
));
|
||||
assert!(matches!(
|
||||
evs[1],
|
||||
TraceEvent::TimerCancelled {
|
||||
state: SC,
|
||||
timer: T_COUNTING
|
||||
}
|
||||
));
|
||||
assert!(matches!(
|
||||
evs[2],
|
||||
TraceEvent::TimerArmed {
|
||||
state: SD,
|
||||
timer: T_DONE,
|
||||
ns: 20_000_000
|
||||
}
|
||||
));
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_timer_byte_deterministic() {
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Tim::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Stop).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..10 {
|
||||
assert_eq!(first, run().await, "diverged on run {i}");
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_timer_state_cancel_uses_correct_state_id() {
|
||||
// The TimerCancelled.state must be SC, not SR or any other.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Tim::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Stop).await;
|
||||
let cancels: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::TimerCancelled { state, .. } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(cancels, vec![SC]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,135 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for parent-vs-child timer interaction.
|
||||
//!
|
||||
//! Spec: "Descending into a child state is not an exit — the parent's
|
||||
//! timers keep running."
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use core::time::Duration;
|
||||
use hsmc::{statechart, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Halt,
|
||||
}
|
||||
|
||||
// Parent has a 100ms timer. Default-descend into ChildA. ChildA has no timer.
|
||||
statechart! {
|
||||
Pt {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(Parent);
|
||||
terminate(Halt);
|
||||
|
||||
state Parent {
|
||||
entry: p_in;
|
||||
exit: p_out;
|
||||
default(ChildA);
|
||||
on(after Duration::from_millis(100)) => Done;
|
||||
state ChildA {
|
||||
entry: ca_in;
|
||||
exit: ca_out;
|
||||
}
|
||||
}
|
||||
state Done {
|
||||
entry: d_in;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl PtActions for PtActionContext<'_> {
|
||||
async fn p_in(&mut self) {}
|
||||
async fn p_out(&mut self) {}
|
||||
async fn ca_in(&mut self) {}
|
||||
async fn ca_out(&mut self) {}
|
||||
async fn d_in(&mut self) {}
|
||||
}
|
||||
|
||||
const SP: u16 = 1;
|
||||
const T_PARENT: u16 = 0;
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_parent_timer_armed_before_child_entered() {
|
||||
// Parent's timer arms during Parent's entry; THEN default-descends into ChildA.
|
||||
// So the order is: TimerArmed(Parent) before Entered(ChildA).
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Pt::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let j = m.take_journal();
|
||||
let armed_idx = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::TimerArmed { state: SP, .. }))
|
||||
.unwrap();
|
||||
let child_entered_idx = j
|
||||
.iter()
|
||||
.position(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::Entered { state: 2 } // ChildA = id 2
|
||||
)
|
||||
})
|
||||
.unwrap();
|
||||
assert!(
|
||||
armed_idx < child_entered_idx,
|
||||
"TimerArmed (Parent) at {} must precede Entered (ChildA) at {}",
|
||||
armed_idx,
|
||||
child_entered_idx
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_parent_timer_only_one_arm_in_initial_descent() {
|
||||
// Only Parent has a timer. ChildA has none.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Pt::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let armed: Vec<u16> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::TimerArmed { state, .. } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(armed, vec![SP]);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_parent_timer_cancelled_on_termination() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Pt::new(Ctx);
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let cancels: Vec<&TraceEvent> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::TimerCancelled { .. }))
|
||||
.collect();
|
||||
// Termination unwinds all states. Parent's timer is cancelled when Parent exits.
|
||||
assert_eq!(
|
||||
cancels.len(),
|
||||
1,
|
||||
"expected exactly 1 TimerCancelled (Parent's), got {:?}",
|
||||
cancels
|
||||
);
|
||||
assert!(matches!(
|
||||
cancels[0],
|
||||
TraceEvent::TimerCancelled {
|
||||
state: SP,
|
||||
timer: T_PARENT
|
||||
}
|
||||
));
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,403 @@
|
||||
#![allow(dead_code)]
|
||||
//! Deterministic-flow tests for UP-TRANSITIONS (target is on active path, target ≠ I).
|
||||
//!
|
||||
//! Spec section "Transitioning to one of your parents (the important one)":
|
||||
//! When you transition to an ancestor of the current state, you exit the
|
||||
//! current state and any states between, but you do NOT re-enter the
|
||||
//! ancestor. ... You cannot enter a state you never left.
|
||||
//!
|
||||
//! Spec invariants for up-transitions:
|
||||
//! - The ancestor's entry actions don't fire.
|
||||
//! - The ancestor's `default` is not followed.
|
||||
//! - The ancestor's timers don't restart.
|
||||
//! - The ancestor's durings keep running.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent, TransitionReason};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
UpToA,
|
||||
UpToB,
|
||||
UpToC,
|
||||
Halt,
|
||||
}
|
||||
|
||||
// Hierarchy: Root → A → B → C → D
|
||||
// Up-transitions on D and intermediate states fire to ancestors.
|
||||
statechart! {
|
||||
Up {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
default(A);
|
||||
terminate(Halt);
|
||||
|
||||
entry: r_in;
|
||||
exit: r_out;
|
||||
|
||||
state A {
|
||||
entry: a_in;
|
||||
exit: a_out;
|
||||
default(B);
|
||||
state B {
|
||||
entry: b_in;
|
||||
exit: b_out;
|
||||
default(C);
|
||||
state C {
|
||||
entry: c_in;
|
||||
exit: c_out;
|
||||
default(D);
|
||||
state D {
|
||||
entry: d_in;
|
||||
exit: d_out;
|
||||
on(UpToA) => A;
|
||||
on(UpToB) => B;
|
||||
on(UpToC) => C;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl UpActions for UpActionContext<'_> {
|
||||
async fn r_in(&mut self) {}
|
||||
async fn r_out(&mut self) {}
|
||||
async fn a_in(&mut self) {}
|
||||
async fn a_out(&mut self) {}
|
||||
async fn b_in(&mut self) {}
|
||||
async fn b_out(&mut self) {}
|
||||
async fn c_in(&mut self) {}
|
||||
async fn c_out(&mut self) {}
|
||||
async fn d_in(&mut self) {}
|
||||
async fn d_out(&mut self) {}
|
||||
}
|
||||
|
||||
const SR: u16 = 0;
|
||||
const SA: u16 = 1;
|
||||
const SB: u16 = 2;
|
||||
const SC: u16 = 3;
|
||||
const SD: u16 = 4;
|
||||
const A_R_IN: u16 = 0;
|
||||
const A_R_OUT: u16 = 1;
|
||||
const A_A_IN: u16 = 2;
|
||||
const A_A_OUT: u16 = 3;
|
||||
const A_B_IN: u16 = 4;
|
||||
const A_B_OUT: u16 = 5;
|
||||
const A_C_IN: u16 = 6;
|
||||
const A_C_OUT: u16 = 7;
|
||||
const A_D_IN: u16 = 8;
|
||||
const A_D_OUT: u16 = 9;
|
||||
// Event ids in first-seen order during IR build (D's handlers, in declaration order).
|
||||
const E_UPTOA: u16 = 0;
|
||||
const E_UPTOB: u16 = 1;
|
||||
const E_UPTOC: u16 = 2;
|
||||
|
||||
fn entry(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Entry,
|
||||
}
|
||||
}
|
||||
fn exit_(state: u16, action: u16) -> TraceEvent {
|
||||
TraceEvent::ActionInvoked {
|
||||
state,
|
||||
action,
|
||||
kind: ActionKind::Exit,
|
||||
}
|
||||
}
|
||||
fn initial_descent() -> Vec<TraceEvent> {
|
||||
vec![
|
||||
TraceEvent::Started {
|
||||
chart_hash: Up::<8>::CHART_HASH,
|
||||
},
|
||||
TraceEvent::EnterBegan { state: SR },
|
||||
entry(SR, A_R_IN),
|
||||
TraceEvent::Entered { state: SR },
|
||||
TraceEvent::EnterBegan { state: SA },
|
||||
entry(SA, A_A_IN),
|
||||
TraceEvent::Entered { state: SA },
|
||||
TraceEvent::EnterBegan { state: SB },
|
||||
entry(SB, A_B_IN),
|
||||
TraceEvent::Entered { state: SB },
|
||||
TraceEvent::EnterBegan { state: SC },
|
||||
entry(SC, A_C_IN),
|
||||
TraceEvent::Entered { state: SC },
|
||||
TraceEvent::EnterBegan { state: SD },
|
||||
entry(SD, A_D_IN),
|
||||
TraceEvent::Entered { state: SD },
|
||||
]
|
||||
}
|
||||
fn assert_journal(actual: &[TraceEvent], expected: &[TraceEvent]) {
|
||||
let mismatch = actual.iter().zip(expected.iter()).position(|(a, e)| a != e);
|
||||
if let Some(i) = mismatch {
|
||||
panic!(
|
||||
"mismatch at index {}\n actual: {:?}\n expected: {:?}",
|
||||
i,
|
||||
actual.get(i),
|
||||
expected.get(i)
|
||||
);
|
||||
}
|
||||
assert_eq!(
|
||||
actual.len(),
|
||||
expected.len(),
|
||||
"length mismatch: actual {} vs expected {}",
|
||||
actual.len(),
|
||||
expected.len()
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_up_to_immediate_grandparent() {
|
||||
// D → C: exit D only. C is target, not exited, not re-entered.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Up::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToC).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
let mut expected = initial_descent();
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_UPTOC },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SD,
|
||||
event: E_UPTOC,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SD),
|
||||
to: SC,
|
||||
reason: TransitionReason::Event { event: E_UPTOC },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SD },
|
||||
exit_(SD, A_D_OUT),
|
||||
TraceEvent::Exited { state: SD },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SD),
|
||||
to: SC,
|
||||
},
|
||||
]);
|
||||
assert_journal(&actual, &expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_up_two_levels() {
|
||||
// D → B: exit D, exit C. B is target, not exited.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Up::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToB).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
let mut expected = initial_descent();
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_UPTOB },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SD,
|
||||
event: E_UPTOB,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SD),
|
||||
to: SB,
|
||||
reason: TransitionReason::Event { event: E_UPTOB },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SD },
|
||||
exit_(SD, A_D_OUT),
|
||||
TraceEvent::Exited { state: SD },
|
||||
TraceEvent::ExitBegan { state: SC },
|
||||
exit_(SC, A_C_OUT),
|
||||
TraceEvent::Exited { state: SC },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SD),
|
||||
to: SB,
|
||||
},
|
||||
]);
|
||||
assert_journal(&actual, &expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_up_three_levels_to_a() {
|
||||
// D → A: exit D, C, B. A is target, not exited.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Up::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToA).await;
|
||||
let actual = m.take_journal();
|
||||
|
||||
let mut expected = initial_descent();
|
||||
expected.extend(vec![
|
||||
TraceEvent::EventReceived { event: E_UPTOA },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: SD,
|
||||
event: E_UPTOA,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(SD),
|
||||
to: SA,
|
||||
reason: TransitionReason::Event { event: E_UPTOA },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: SD },
|
||||
exit_(SD, A_D_OUT),
|
||||
TraceEvent::Exited { state: SD },
|
||||
TraceEvent::ExitBegan { state: SC },
|
||||
exit_(SC, A_C_OUT),
|
||||
TraceEvent::Exited { state: SC },
|
||||
TraceEvent::ExitBegan { state: SB },
|
||||
exit_(SB, A_B_OUT),
|
||||
TraceEvent::Exited { state: SB },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(SD),
|
||||
to: SA,
|
||||
},
|
||||
]);
|
||||
assert_journal(&actual, &expected);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_up_target_not_re_entered() {
|
||||
// After D → A: A must NOT appear in any Entered event after the initial descent.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Up::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToA).await;
|
||||
let j = m.take_journal();
|
||||
let split = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::EventDelivered { event: E_UPTOA, .. }))
|
||||
.unwrap();
|
||||
let a_re_entered = j[split..]
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::Entered { state: SA }))
|
||||
.count();
|
||||
assert_eq!(
|
||||
a_re_entered, 0,
|
||||
"target A must not re-enter on up-transition"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_up_target_action_not_fired() {
|
||||
// After D → A: a_in must NOT fire after the initial descent.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Up::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToA).await;
|
||||
let j = m.take_journal();
|
||||
let split = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::EventDelivered { event: E_UPTOA, .. }))
|
||||
.unwrap();
|
||||
let a_in_after = j[split..]
|
||||
.iter()
|
||||
.filter(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::ActionInvoked {
|
||||
state: SA,
|
||||
action: A_A_IN,
|
||||
..
|
||||
}
|
||||
)
|
||||
})
|
||||
.count();
|
||||
assert_eq!(
|
||||
a_in_after, 0,
|
||||
"target's entry action must not fire on up-transition"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_up_no_default_descent() {
|
||||
// After D → A: no default-descent. The journal stops with Exited(B).
|
||||
// A is the new innermost active state, with no active child.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Up::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToA).await;
|
||||
let j = m.take_journal();
|
||||
let split = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::EventDelivered { event: E_UPTOA, .. }))
|
||||
.unwrap();
|
||||
// Nothing after this slice should be Entered (no descent).
|
||||
let entered_after = j[split..]
|
||||
.iter()
|
||||
.filter(|e| matches!(e, TraceEvent::Entered { .. }))
|
||||
.count();
|
||||
assert_eq!(entered_after, 0, "up-transition: no default-descent");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_up_current_state_is_target_after() {
|
||||
// After D → B, the innermost active state is B (composite, no active child).
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Up::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToB).await;
|
||||
// current_state() should return B's public variant.
|
||||
// Indirect check: the most recent Entered (B's, from initial descent) is the
|
||||
// last Entered before the up-transition; nothing after.
|
||||
let j = m.take_journal();
|
||||
let last_entered = j
|
||||
.iter()
|
||||
.enumerate()
|
||||
.rev()
|
||||
.find(|(_, e)| matches!(e, TraceEvent::Entered { .. }))
|
||||
.map(|(i, _)| i);
|
||||
let split = j
|
||||
.iter()
|
||||
.position(|e| matches!(e, TraceEvent::TransitionFired { .. }))
|
||||
.unwrap();
|
||||
// The last Entered event must be BEFORE the transition.
|
||||
assert!(
|
||||
last_entered.unwrap() < split,
|
||||
"up-transition: no entries after the transition fires"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn det_up_chained_then_lateral() {
|
||||
// D → C, then C is a leaf with no children, so this becomes the new
|
||||
// innermost. From C we don't have any other handlers, so test ends here.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Up::new(Ctx);
|
||||
let _ = m.dispatch(Ev::UpToC).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
let j = m.take_journal();
|
||||
// After UpToC, we should have Exited(D) but C remains. Halt then exits
|
||||
// C → B → A → Root.
|
||||
let exits: Vec<u16> = j
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Exited { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(
|
||||
exits,
|
||||
vec![SD, SC, SB, SA, SR],
|
||||
"up to C, then terminate exits remaining path"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,90 @@
|
||||
//! Dumps a journal for visual inspection. Run with:
|
||||
//!
|
||||
//! cargo test -p hsmc --features tokio,journal --test journal_dump -- --nocapture
|
||||
//!
|
||||
//! Not an assertion — just shows the actual sequence so we can sanity-check
|
||||
//! that "EVERYTHING" is journaled.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::statechart;
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx {
|
||||
pub n: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq)]
|
||||
pub enum Ev {
|
||||
Go,
|
||||
Beep,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Dump {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
|
||||
default(Idle);
|
||||
terminate(Halt);
|
||||
|
||||
entry: root_in;
|
||||
exit: root_out;
|
||||
|
||||
state Idle {
|
||||
entry: idle_in;
|
||||
exit: idle_out;
|
||||
on(Go) => Active;
|
||||
on(Beep) => beep_at_idle;
|
||||
}
|
||||
state Active {
|
||||
entry: active_in;
|
||||
exit: active_out;
|
||||
default(Sub);
|
||||
state Sub {
|
||||
entry: sub_in;
|
||||
exit: sub_out;
|
||||
on(Beep) => beep_at_sub;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl DumpActions for DumpActionContext<'_> {
|
||||
async fn root_in(&mut self) {
|
||||
self.n += 1;
|
||||
}
|
||||
async fn root_out(&mut self) {}
|
||||
async fn idle_in(&mut self) {}
|
||||
async fn idle_out(&mut self) {}
|
||||
async fn active_in(&mut self) {}
|
||||
async fn active_out(&mut self) {}
|
||||
async fn sub_in(&mut self) {}
|
||||
async fn sub_out(&mut self) {}
|
||||
async fn beep_at_idle(&mut self) {}
|
||||
async fn beep_at_sub(&mut self) {}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn dump_journal() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Dump::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Beep).await;
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let _ = m.dispatch(Ev::Beep).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
|
||||
println!(
|
||||
"\n=== JOURNAL DUMP (CHART_HASH={:#x}) ===",
|
||||
Dump::<8>::CHART_HASH
|
||||
);
|
||||
for (i, e) in m.journal().iter().enumerate() {
|
||||
println!(" {:>3}: {:?}", i, e);
|
||||
}
|
||||
println!("=== END ({} events) ===\n", m.journal().len());
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,190 @@
|
||||
//! Replay tests: a hand-built EXPECTED journal compared byte-for-byte against
|
||||
//! the ACTUAL journal produced by running the chart with a fixed event
|
||||
//! sequence. This is the canonical correctness check the user asked for —
|
||||
//! "EVERYTHING in the sequence has to be journaled and compared against the
|
||||
//! expected sequence."
|
||||
//!
|
||||
//! When the codegen drifts (an entry actions reorders, a timer arms in a
|
||||
//! different place, an event dispatches to a different state), exactly one
|
||||
//! line of the expected vector mismatches and the test fails with a
|
||||
//! pinpoint diff.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent, TransitionReason};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone, PartialEq)]
|
||||
pub enum Ev {
|
||||
Go,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
Replay {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
|
||||
default(Idle);
|
||||
terminate(Halt);
|
||||
|
||||
entry: root_in;
|
||||
exit: root_out;
|
||||
|
||||
state Idle {
|
||||
entry: idle_in;
|
||||
exit: idle_out;
|
||||
on(Go) => Active;
|
||||
}
|
||||
state Active {
|
||||
entry: active_in;
|
||||
exit: active_out;
|
||||
default(Sub);
|
||||
state Sub {
|
||||
entry: sub_in;
|
||||
exit: sub_out;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl ReplayActions for ReplayActionContext<'_> {
|
||||
async fn root_in(&mut self) {}
|
||||
async fn root_out(&mut self) {}
|
||||
async fn idle_in(&mut self) {}
|
||||
async fn idle_out(&mut self) {}
|
||||
async fn active_in(&mut self) {}
|
||||
async fn active_out(&mut self) {}
|
||||
async fn sub_in(&mut self) {}
|
||||
async fn sub_out(&mut self) {}
|
||||
}
|
||||
|
||||
// State indices.
|
||||
const ST_ROOT: u16 = 0;
|
||||
const ST_IDLE: u16 = 1;
|
||||
const ST_ACTIVE: u16 = 2;
|
||||
const ST_SUB: u16 = 3;
|
||||
|
||||
// Action indices.
|
||||
const A_ROOT_IN: u16 = 0;
|
||||
const A_ROOT_OUT: u16 = 1;
|
||||
const A_IDLE_IN: u16 = 2;
|
||||
const A_IDLE_OUT: u16 = 3;
|
||||
const A_ACTIVE_IN: u16 = 4;
|
||||
const A_ACTIVE_OUT: u16 = 5;
|
||||
const A_SUB_IN: u16 = 6;
|
||||
const A_SUB_OUT: u16 = 7;
|
||||
|
||||
// Event indices.
|
||||
const E_GO: u16 = 0;
|
||||
const E_HALT: u16 = 1;
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn replay_full_lifecycle_matches_expected() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = Replay::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
|
||||
let actual = m.take_journal();
|
||||
|
||||
let expected: Vec<TraceEvent> = vec![
|
||||
// ── First step: enter the chart ──
|
||||
TraceEvent::Started {
|
||||
chart_hash: Replay::<8>::CHART_HASH,
|
||||
},
|
||||
TraceEvent::EnterBegan { state: ST_ROOT },
|
||||
TraceEvent::ActionInvoked {
|
||||
state: ST_ROOT,
|
||||
action: A_ROOT_IN,
|
||||
kind: ActionKind::Entry,
|
||||
},
|
||||
TraceEvent::Entered { state: ST_ROOT },
|
||||
TraceEvent::EnterBegan { state: ST_IDLE },
|
||||
TraceEvent::ActionInvoked {
|
||||
state: ST_IDLE,
|
||||
action: A_IDLE_IN,
|
||||
kind: ActionKind::Entry,
|
||||
},
|
||||
TraceEvent::Entered { state: ST_IDLE },
|
||||
// ── Go event delivered to Idle, transition to Active → Sub ──
|
||||
TraceEvent::EventReceived { event: E_GO },
|
||||
TraceEvent::EventDelivered {
|
||||
handler_state: ST_IDLE,
|
||||
event: E_GO,
|
||||
},
|
||||
TraceEvent::TransitionFired {
|
||||
from: Some(ST_IDLE),
|
||||
to: ST_ACTIVE,
|
||||
reason: TransitionReason::Event { event: E_GO },
|
||||
},
|
||||
TraceEvent::ExitBegan { state: ST_IDLE },
|
||||
TraceEvent::ActionInvoked {
|
||||
state: ST_IDLE,
|
||||
action: A_IDLE_OUT,
|
||||
kind: ActionKind::Exit,
|
||||
},
|
||||
TraceEvent::Exited { state: ST_IDLE },
|
||||
TraceEvent::EnterBegan { state: ST_ACTIVE },
|
||||
TraceEvent::ActionInvoked {
|
||||
state: ST_ACTIVE,
|
||||
action: A_ACTIVE_IN,
|
||||
kind: ActionKind::Entry,
|
||||
},
|
||||
TraceEvent::Entered { state: ST_ACTIVE },
|
||||
TraceEvent::EnterBegan { state: ST_SUB },
|
||||
TraceEvent::ActionInvoked {
|
||||
state: ST_SUB,
|
||||
action: A_SUB_IN,
|
||||
kind: ActionKind::Entry,
|
||||
},
|
||||
TraceEvent::Entered { state: ST_SUB },
|
||||
TraceEvent::TransitionComplete {
|
||||
from: Some(ST_IDLE),
|
||||
to: ST_ACTIVE,
|
||||
},
|
||||
// ── Halt event triggers termination: exit Sub → Active → root, then Terminated ──
|
||||
TraceEvent::EventReceived { event: E_HALT },
|
||||
TraceEvent::TerminateRequested { event: E_HALT },
|
||||
TraceEvent::ExitBegan { state: ST_SUB },
|
||||
TraceEvent::ActionInvoked {
|
||||
state: ST_SUB,
|
||||
action: A_SUB_OUT,
|
||||
kind: ActionKind::Exit,
|
||||
},
|
||||
TraceEvent::Exited { state: ST_SUB },
|
||||
TraceEvent::ExitBegan { state: ST_ACTIVE },
|
||||
TraceEvent::ActionInvoked {
|
||||
state: ST_ACTIVE,
|
||||
action: A_ACTIVE_OUT,
|
||||
kind: ActionKind::Exit,
|
||||
},
|
||||
TraceEvent::Exited { state: ST_ACTIVE },
|
||||
TraceEvent::ExitBegan { state: ST_ROOT },
|
||||
TraceEvent::ActionInvoked {
|
||||
state: ST_ROOT,
|
||||
action: A_ROOT_OUT,
|
||||
kind: ActionKind::Exit,
|
||||
},
|
||||
TraceEvent::Exited { state: ST_ROOT },
|
||||
TraceEvent::Terminated,
|
||||
];
|
||||
|
||||
let mismatch_at = actual
|
||||
.iter()
|
||||
.zip(expected.iter())
|
||||
.position(|(a, e)| a != e)
|
||||
.map(|i| i.to_string())
|
||||
.unwrap_or_else(|| "<length-mismatch>".to_string());
|
||||
assert_eq!(
|
||||
actual, expected,
|
||||
"journal divergence at index {}",
|
||||
mismatch_at
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
//! Replay test for emit() journaling.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Trigger,
|
||||
Followup,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
EmitProbe {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
|
||||
default(A);
|
||||
terminate(Halt);
|
||||
|
||||
state A {
|
||||
on(Trigger) => emit_followup;
|
||||
on(Followup) => B;
|
||||
}
|
||||
state B {
|
||||
entry: noop;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl EmitProbeActions for EmitProbeActionContext<'_> {
|
||||
async fn emit_followup(&mut self) {
|
||||
self.emit(Ev::Followup).unwrap();
|
||||
}
|
||||
async fn noop(&mut self) {}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn emit_queued_appears_in_journal() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = EmitProbe::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Trigger).await;
|
||||
|
||||
let saw_emit = m
|
||||
.journal()
|
||||
.iter()
|
||||
.any(|e| matches!(e, TraceEvent::EmitQueued { .. }));
|
||||
assert!(
|
||||
saw_emit,
|
||||
"journal must contain EmitQueued, got {:?}",
|
||||
m.journal()
|
||||
);
|
||||
|
||||
// The follow-up event MUST be delivered (proving the queue actually
|
||||
// drained the emit'd event).
|
||||
let delivered_followup = m.journal().iter().any(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::EventDelivered { event: 1, .. } // 1 = Followup (Trigger=0, Followup=1)
|
||||
)
|
||||
});
|
||||
assert!(
|
||||
delivered_followup,
|
||||
"expected Followup to be delivered after emit"
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,93 @@
|
||||
//! Replay test for timer arm + cancel paths.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, TraceEvent};
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx {
|
||||
pub fired: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Stop,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
TimerProbe {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
|
||||
default(Counting);
|
||||
terminate(Halt);
|
||||
|
||||
state Counting {
|
||||
entry: noop;
|
||||
exit: noop2;
|
||||
on(after hsmc::Duration::from_millis(100)) => Done;
|
||||
on(Stop) => Done;
|
||||
}
|
||||
state Done {
|
||||
entry: noop3;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl TimerProbeActions for TimerProbeActionContext<'_> {
|
||||
async fn noop(&mut self) {}
|
||||
async fn noop2(&mut self) {}
|
||||
async fn noop3(&mut self) {}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn timer_arm_then_cancel_journals_both() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TimerProbe::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Stop).await;
|
||||
|
||||
let timer_events: Vec<&TraceEvent> = m
|
||||
.journal()
|
||||
.iter()
|
||||
.filter(|e| {
|
||||
matches!(
|
||||
e,
|
||||
TraceEvent::TimerArmed { .. }
|
||||
| TraceEvent::TimerCancelled { .. }
|
||||
| TraceEvent::TimerFired { .. }
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
|
||||
assert_eq!(
|
||||
timer_events.len(),
|
||||
2,
|
||||
"expected 2 timer events, got {:?}",
|
||||
timer_events
|
||||
);
|
||||
assert!(
|
||||
matches!(
|
||||
timer_events[0],
|
||||
TraceEvent::TimerArmed {
|
||||
state: 1,
|
||||
timer: 0,
|
||||
ns: 100_000_000
|
||||
}
|
||||
),
|
||||
"got {:?}",
|
||||
timer_events[0]
|
||||
);
|
||||
assert!(
|
||||
matches!(
|
||||
timer_events[1],
|
||||
TraceEvent::TimerCancelled { state: 1, timer: 0 }
|
||||
),
|
||||
"got {:?}",
|
||||
timer_events[1]
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
@@ -0,0 +1,267 @@
|
||||
//! Smoke tests for the deterministic execution journal (`feature = "journal"`).
|
||||
//!
|
||||
//! Every observable atom — entries, exits, action invocations (with kind),
|
||||
//! during start/cancel, timer arm/cancel/fire, queued emits, event delivery,
|
||||
//! transitions, termination — must appear in the journal in canonical order
|
||||
//! for a fixed `(chart, ctx, event sequence)` input. These tests pin down
|
||||
//! that order on small chart shapes so any regression in codegen is caught
|
||||
//! immediately.
|
||||
//!
|
||||
//! Tests run only when both `tokio` and `journal` features are enabled.
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, ActionKind, TraceEvent};
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
// Small chart: A → B on Go, with entry/exit actions in a hierarchy.
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx {
|
||||
pub log: Vec<&'static str>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq)]
|
||||
pub enum Ev {
|
||||
Go,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
JournalProbe {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
|
||||
default(Idle);
|
||||
terminate(Halt);
|
||||
|
||||
entry: root_in;
|
||||
exit: root_out;
|
||||
|
||||
state Idle {
|
||||
entry: idle_in;
|
||||
exit: idle_out;
|
||||
on(Go) => Active;
|
||||
}
|
||||
state Active {
|
||||
entry: active_in;
|
||||
exit: active_out;
|
||||
default(Sub);
|
||||
state Sub {
|
||||
entry: sub_in;
|
||||
exit: sub_out;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl JournalProbeActions for JournalProbeActionContext<'_> {
|
||||
async fn root_in(&mut self) {
|
||||
self.log.push("root_in");
|
||||
}
|
||||
async fn root_out(&mut self) {
|
||||
self.log.push("root_out");
|
||||
}
|
||||
async fn idle_in(&mut self) {
|
||||
self.log.push("idle_in");
|
||||
}
|
||||
async fn idle_out(&mut self) {
|
||||
self.log.push("idle_out");
|
||||
}
|
||||
async fn active_in(&mut self) {
|
||||
self.log.push("active_in");
|
||||
}
|
||||
async fn active_out(&mut self) {
|
||||
self.log.push("active_out");
|
||||
}
|
||||
async fn sub_in(&mut self) {
|
||||
self.log.push("sub_in");
|
||||
}
|
||||
async fn sub_out(&mut self) {
|
||||
self.log.push("sub_out");
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn journal_records_initial_descent() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = JournalProbe::new(Ctx::default());
|
||||
// Drive the initial entry chain by stepping once with no event.
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
|
||||
let j = m.journal();
|
||||
|
||||
// First event must be Started.
|
||||
assert!(matches!(j[0], TraceEvent::Started { .. }));
|
||||
// Started carries the chart's stable hash.
|
||||
if let TraceEvent::Started { chart_hash } = j[0] {
|
||||
assert_eq!(chart_hash, JournalProbe::<8>::CHART_HASH);
|
||||
}
|
||||
|
||||
// We expect (in order, for the initial descent root → Idle):
|
||||
// Started
|
||||
// Entered(root)
|
||||
// ActionInvoked(root, root_in, Entry)
|
||||
// Entered(Idle)
|
||||
// ActionInvoked(Idle, idle_in, Entry)
|
||||
// ... (then the Go event delivery / transition / sub entry)
|
||||
let states_entered: Vec<u16> = j
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Entered { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
// At minimum we entered root (id 0), then Idle, then Active, then Sub.
|
||||
assert_eq!(
|
||||
states_entered.len(),
|
||||
4,
|
||||
"expected 4 Entered events, got {:?}",
|
||||
j
|
||||
);
|
||||
|
||||
// Action kinds appear in order Entry → Handler (none here) → Exit.
|
||||
let kinds: Vec<ActionKind> = j
|
||||
.iter()
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::ActionInvoked { kind, .. } => Some(*kind),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
// Actions on the journey: Entry x4 (root, idle, active, sub),
|
||||
// Exit x1 (idle), Entry x2 (active, sub) — wait no:
|
||||
// Initial descent is root → Idle. Entries: root_in, idle_in.
|
||||
// Then Go fires: Idle exits (idle_out), Active enters (active_in),
|
||||
// Sub enters (sub_in).
|
||||
// Total: Entry(root), Entry(idle), Exit(idle), Entry(active), Entry(sub).
|
||||
let entry_count = kinds.iter().filter(|k| **k == ActionKind::Entry).count();
|
||||
let exit_count = kinds.iter().filter(|k| **k == ActionKind::Exit).count();
|
||||
assert_eq!(
|
||||
entry_count, 4,
|
||||
"expected 4 entry actions, got kinds {:?}",
|
||||
kinds
|
||||
);
|
||||
assert_eq!(
|
||||
exit_count, 1,
|
||||
"expected 1 exit action, got kinds {:?}",
|
||||
kinds
|
||||
);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn journal_includes_transition_event() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = JournalProbe::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
|
||||
let saw_transition = m
|
||||
.journal()
|
||||
.iter()
|
||||
.any(|e| matches!(e, TraceEvent::TransitionFired { .. }));
|
||||
assert!(saw_transition, "journal must contain TransitionFired");
|
||||
|
||||
let saw_event_delivered = m
|
||||
.journal()
|
||||
.iter()
|
||||
.any(|e| matches!(e, TraceEvent::EventDelivered { .. }));
|
||||
assert!(saw_event_delivered, "journal must contain EventDelivered");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn journal_records_termination() {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = JournalProbe::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
|
||||
let j = m.journal();
|
||||
assert!(
|
||||
matches!(j.last(), Some(TraceEvent::Terminated)),
|
||||
"journal must end with Terminated, got tail: {:?}",
|
||||
&j[j.len().saturating_sub(3)..]
|
||||
);
|
||||
|
||||
// Termination exits all states from leaf to root (Sub → Active → Idle? No,
|
||||
// Idle was already exited on Go. After Halt the active path is
|
||||
// root → Active → Sub. Exits: Sub, Active, root.
|
||||
let post_halt_exits: Vec<u16> = j.iter()
|
||||
.skip_while(|e| !matches!(e, TraceEvent::EventDelivered { .. } if matches!(j.iter().rev().find(|x| matches!(x, TraceEvent::EventDelivered { .. })), Some(_))))
|
||||
.filter_map(|e| match e {
|
||||
TraceEvent::Exited { state } => Some(*state),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
// We at least exited 4 times across the run (idle once, then sub/active/root on terminate).
|
||||
assert!(post_halt_exits.len() >= 3, "expected at least 3 exits across the run, got {:?}", j);
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn journal_is_byte_deterministic_across_runs() {
|
||||
// Same chart, same context, same event sequence ⇒ identical journal.
|
||||
let run = || async {
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = JournalProbe::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await
|
||||
};
|
||||
let first = run().await;
|
||||
for i in 1..10 {
|
||||
let again = run().await;
|
||||
assert_eq!(first, again, "journal divergence on run #{}", i);
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn clear_journal_empties_the_journal() {
|
||||
// Pins down `JournalSink::clear`: after dispatching events that
|
||||
// produce journal entries, calling `clear_journal()` must empty
|
||||
// the journal. Subsequent `journal()` returns an empty slice;
|
||||
// `take_journal()` returns an empty Vec.
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = JournalProbe::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
assert!(
|
||||
!m.journal().is_empty(),
|
||||
"journal should have entries before clear"
|
||||
);
|
||||
|
||||
m.clear_journal();
|
||||
assert!(
|
||||
m.journal().is_empty(),
|
||||
"journal must be empty after clear_journal()"
|
||||
);
|
||||
let taken = m.take_journal();
|
||||
assert!(taken.is_empty(), "take_journal() after clear must be empty");
|
||||
})
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn chart_hash_is_stable() {
|
||||
// Two instances of the same chart must agree on CHART_HASH.
|
||||
let _m1 = JournalProbe::new(Ctx::default());
|
||||
let _m2 = JournalProbe::new(Ctx::default());
|
||||
assert_eq!(
|
||||
JournalProbe::<8>::CHART_HASH,
|
||||
JournalProbe::<8>::CHART_HASH,
|
||||
"chart hash must be stable across instantiations"
|
||||
);
|
||||
// CHART_HASH must be nonzero — proves the FNV-1a fingerprint actually ran.
|
||||
assert_ne!(JournalProbe::<8>::CHART_HASH, 0);
|
||||
}
|
||||
@@ -0,0 +1,429 @@
|
||||
//! Verifies the textual format of the unified observation pipeline's
|
||||
//! `trace-log` sink line-for-line.
|
||||
//!
|
||||
//! Each `__chart_observe!` arm has a stable logfmt-style format:
|
||||
//!
|
||||
//! `[statechart:<Name>] <verb> key=value key=value …`
|
||||
//!
|
||||
//! These tests pin every verb's exact rendering so a real-life log capture
|
||||
//! can be diffed against expected behavior. The chart is exercised through
|
||||
//! both the journal sink (so we can assert atom-by-atom equivalence) and
|
||||
//! the trace-log sink (so we can assert the rendered strings).
|
||||
|
||||
#![cfg(all(feature = "tokio", feature = "journal", feature = "trace-log"))]
|
||||
#![allow(unexpected_cfgs)]
|
||||
|
||||
use hsmc::{statechart, Duration, TraceEvent, TransitionReason};
|
||||
use std::sync::{Mutex, MutexGuard, OnceLock};
|
||||
|
||||
// ── Capture sink ─────────────────────────────────────────────────────
|
||||
//
|
||||
// log::set_logger can only be installed once per process. The capture
|
||||
// holds a single Vec<String> shared across all tests, plus a global
|
||||
// `TEST_LOCK` that each test holds across its drive-then-assert
|
||||
// section so concurrent tests don't interleave their captured lines.
|
||||
|
||||
struct Capture {
|
||||
lines: Mutex<Vec<String>>,
|
||||
}
|
||||
|
||||
impl log::Log for Capture {
|
||||
fn enabled(&self, _: &log::Metadata<'_>) -> bool {
|
||||
true
|
||||
}
|
||||
fn log(&self, record: &log::Record<'_>) {
|
||||
if let Ok(mut g) = self.lines.lock() {
|
||||
g.push(format!("{}", record.args()));
|
||||
}
|
||||
}
|
||||
fn flush(&self) {}
|
||||
}
|
||||
|
||||
static CAPTURE: OnceLock<&'static Capture> = OnceLock::new();
|
||||
static TEST_LOCK: Mutex<()> = Mutex::new(());
|
||||
|
||||
fn install_capture() -> &'static Capture {
|
||||
*CAPTURE.get_or_init(|| {
|
||||
let leaked: &'static Capture = Box::leak(Box::new(Capture {
|
||||
lines: Mutex::new(Vec::new()),
|
||||
}));
|
||||
let _ = log::set_logger(leaked);
|
||||
log::set_max_level(log::LevelFilter::Trace);
|
||||
leaked
|
||||
})
|
||||
}
|
||||
|
||||
/// RAII helper. Acquire before driving the chart, drop after assertions
|
||||
/// — keeps `tests::*` from interleaving captured log lines.
|
||||
fn lock_for_test() -> MutexGuard<'static, ()> {
|
||||
install_capture();
|
||||
let g = TEST_LOCK.lock().unwrap_or_else(|p| p.into_inner());
|
||||
// Clear any lines left by a previous test that paniced before
|
||||
// draining (poison case).
|
||||
let cap = CAPTURE.get().unwrap();
|
||||
cap.lines.lock().unwrap().clear();
|
||||
g
|
||||
}
|
||||
|
||||
fn current_lines() -> Vec<String> {
|
||||
let cap = install_capture();
|
||||
cap.lines.lock().unwrap().clone()
|
||||
}
|
||||
|
||||
// ── Test chart ───────────────────────────────────────────────────────
|
||||
//
|
||||
// Covers every observation verb the macro can emit. Two states with
|
||||
// entry/exit actions, a handler that emits and transitions, a timer,
|
||||
// a during, and a terminate event.
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct Ctx {
|
||||
pub buf: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Ev {
|
||||
Go,
|
||||
Step,
|
||||
Halt,
|
||||
}
|
||||
|
||||
statechart! {
|
||||
TraceFmt {
|
||||
context: Ctx;
|
||||
events: Ev;
|
||||
|
||||
default(Idle);
|
||||
terminate(Halt);
|
||||
|
||||
state Idle {
|
||||
entry: idle_in;
|
||||
exit: idle_out;
|
||||
during: tick(buf);
|
||||
on(after Duration::from_secs(60)) => Idle;
|
||||
on(Go) => Active;
|
||||
}
|
||||
state Active {
|
||||
entry: active_in;
|
||||
exit: active_out;
|
||||
on(Step) => bump;
|
||||
on(Halt) => Idle;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async fn tick(_buf: &mut u32) -> Ev {
|
||||
Ev::Step
|
||||
}
|
||||
|
||||
impl TraceFmtActions for TraceFmtActionContext<'_> {
|
||||
async fn idle_in(&mut self) {}
|
||||
async fn idle_out(&mut self) {}
|
||||
async fn active_in(&mut self) {}
|
||||
async fn active_out(&mut self) {}
|
||||
async fn bump(&mut self) {
|
||||
let _ = self.emit(Ev::Halt);
|
||||
}
|
||||
}
|
||||
|
||||
// ── Helpers ──────────────────────────────────────────────────────────
|
||||
|
||||
/// Returns true iff `line` matches the expected `[statechart:TraceFmt] verb …`
|
||||
/// shape. Every line emitted by the dispatcher must.
|
||||
fn well_formed(line: &str) -> bool {
|
||||
line.starts_with("[statechart:TraceFmt] ")
|
||||
}
|
||||
|
||||
/// Filter `lines` to only those whose verb (the first token after the
|
||||
/// prefix) equals `verb`. Useful for asserting on a single verb's lines.
|
||||
fn lines_with_verb<'a>(lines: &'a [String], verb: &str) -> Vec<&'a str> {
|
||||
let prefix = "[statechart:TraceFmt] ";
|
||||
lines
|
||||
.iter()
|
||||
.filter_map(|l| l.strip_prefix(prefix))
|
||||
.filter(|rest| rest.split_whitespace().next() == Some(verb))
|
||||
.map(|s| s.as_ref())
|
||||
.collect()
|
||||
}
|
||||
|
||||
// ── Tests ────────────────────────────────────────────────────────────
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn every_line_uses_statechart_prefix() {
|
||||
let _g = lock_for_test();
|
||||
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
let _ = m.dispatch(Ev::Halt).await;
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
assert!(!lines.is_empty(), "no log lines captured");
|
||||
for l in &lines {
|
||||
assert!(
|
||||
well_formed(l),
|
||||
"line missing [statechart:TraceFmt] prefix: {l:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn enter_and_exit_emit_begin_end_pairs() {
|
||||
let _g = lock_for_test();
|
||||
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
let entering = lines_with_verb(&lines, "entering");
|
||||
let entered = lines_with_verb(&lines, "entered");
|
||||
assert_eq!(
|
||||
entering.len(),
|
||||
entered.len(),
|
||||
"every `entering` must have a matching `entered`"
|
||||
);
|
||||
assert!(entering.contains(&"entering state=TraceFmt"));
|
||||
assert!(entered.contains(&"entered state=TraceFmt"));
|
||||
assert!(entering.contains(&"entering state=Idle"));
|
||||
assert!(entered.contains(&"entered state=Idle"));
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn transition_records_event_reason() {
|
||||
let _g = lock_for_test();
|
||||
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
let begins = lines_with_verb(&lines, "transition-begin");
|
||||
assert!(!begins.is_empty(), "no transition-begin lines captured");
|
||||
let line = begins[0];
|
||||
assert!(
|
||||
line.contains("from=Idle"),
|
||||
"transition-begin missing from=Idle: {line:?}"
|
||||
);
|
||||
assert!(
|
||||
line.contains("to=Active"),
|
||||
"transition-begin missing to=Active: {line:?}"
|
||||
);
|
||||
assert!(
|
||||
line.contains("reason=event:Go"),
|
||||
"transition-begin missing reason=event:Go: {line:?}"
|
||||
);
|
||||
|
||||
let completes = lines_with_verb(&lines, "transition-complete");
|
||||
assert!(
|
||||
!completes.is_empty(),
|
||||
"transition-complete must follow transition-begin"
|
||||
);
|
||||
assert!(completes[0].contains("from=Idle") && completes[0].contains("to=Active"));
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn event_lifecycle_received_then_outcome() {
|
||||
let _g = lock_for_test();
|
||||
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
let received = lines_with_verb(&lines, "event-received");
|
||||
let delivered = lines_with_verb(&lines, "event-delivered");
|
||||
assert!(received.iter().any(|l| l.contains("name=Go")));
|
||||
assert!(delivered
|
||||
.iter()
|
||||
.any(|l| l.contains("name=Go") && l.contains("handler=Idle")));
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn during_emits_started_and_cancelled() {
|
||||
let _g = lock_for_test();
|
||||
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
// Go enters Active, which causes Idle's during to be cancelled.
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
let started = lines_with_verb(&lines, "during-started");
|
||||
let cancelled = lines_with_verb(&lines, "during-cancelled");
|
||||
assert!(started.iter().any(|l| l.contains("during=tick")));
|
||||
assert!(cancelled.iter().any(|l| l.contains("during=tick")));
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn timer_arm_then_cancel_lines() {
|
||||
let _g = lock_for_test();
|
||||
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
let armed = lines_with_verb(&lines, "timer-armed");
|
||||
let cancelled = lines_with_verb(&lines, "timer-cancelled");
|
||||
assert!(
|
||||
armed.iter().any(|l| l.contains("state=Idle")),
|
||||
"timer should arm when Idle is entered"
|
||||
);
|
||||
assert!(
|
||||
cancelled.iter().any(|l| l.contains("state=Idle")),
|
||||
"timer should be cancelled when Idle is exited (Go transition)"
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn emit_queued_appears_for_handler_emit() {
|
||||
let _g = lock_for_test();
|
||||
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
// Step's handler calls emit(Halt).
|
||||
let _ = m.dispatch(Ev::Step).await;
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
let queued = lines_with_verb(&lines, "emit-queued");
|
||||
assert!(
|
||||
queued.iter().any(|l| l.contains("event=Halt")),
|
||||
"expected emit-queued event=Halt line: {lines:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn terminate_records_request_then_terminated() {
|
||||
let _g = lock_for_test();
|
||||
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
// Halt from Active is a transition to Idle (no terminate);
|
||||
// dispatch Halt twice via Idle to actually terminate.
|
||||
// First Go landed us in Active; Halt → Idle (handler).
|
||||
let _ = m.dispatch(Ev::Halt).await; // back to Idle
|
||||
let _ = m.dispatch(Ev::Halt).await; // now terminate
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
let req = lines_with_verb(&lines, "terminate-requested");
|
||||
let term = lines_with_verb(&lines, "terminated");
|
||||
assert!(
|
||||
req.iter().any(|l| l.contains("event=Halt")),
|
||||
"expected terminate-requested event=Halt: {lines:?}"
|
||||
);
|
||||
assert!(
|
||||
!term.is_empty(),
|
||||
"expected a final `terminated` line: {lines:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn started_records_chart_hash() {
|
||||
let _g = lock_for_test();
|
||||
|
||||
tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
let started = lines_with_verb(&lines, "started");
|
||||
assert!(!started.is_empty(), "expected one `started` line");
|
||||
assert!(
|
||||
started[0].contains("chart_hash=0x"),
|
||||
"started must include chart_hash in hex: {:?}",
|
||||
started[0]
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn trace_and_journal_have_matching_atom_count() {
|
||||
// The "one journal, multiple outputs" contract: every TraceEvent
|
||||
// recorded in the journal corresponds to exactly one log line in
|
||||
// the trace, modulo verb-name differences.
|
||||
let _g = lock_for_test();
|
||||
|
||||
let actual = tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
assert_eq!(
|
||||
actual.len(),
|
||||
lines.len(),
|
||||
"journal/trace atom count diverged ({} vs {} lines)",
|
||||
actual.len(),
|
||||
lines.len()
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "current_thread")]
|
||||
async fn transition_reason_in_journal_matches_trace() {
|
||||
// The journal records the structured `TransitionReason::Event { event }`
|
||||
// and the trace renders it as `event:<VariantName>`. They must agree.
|
||||
let _g = lock_for_test();
|
||||
|
||||
let actual = tokio::task::LocalSet::new()
|
||||
.run_until(async {
|
||||
let mut m = TraceFmt::new(Ctx::default());
|
||||
let _ = m.dispatch(Ev::Go).await;
|
||||
m.take_journal()
|
||||
})
|
||||
.await;
|
||||
|
||||
let lines = current_lines();
|
||||
|
||||
let journal_reason = actual.iter().find_map(|e| match e {
|
||||
TraceEvent::TransitionFired { reason, .. } => Some(*reason),
|
||||
_ => None,
|
||||
});
|
||||
let trace_reason_line = lines_with_verb(&lines, "transition-begin")
|
||||
.first()
|
||||
.copied()
|
||||
.map(|s| s.to_string());
|
||||
|
||||
assert_eq!(
|
||||
journal_reason,
|
||||
Some(TransitionReason::Event { event: 0 }),
|
||||
"expected first transition driven by Ev::Go (event id 0)"
|
||||
);
|
||||
assert!(
|
||||
trace_reason_line
|
||||
.as_deref()
|
||||
.is_some_and(|l| l.contains("reason=event:Go")),
|
||||
"trace reason should match journal reason: {trace_reason_line:?}"
|
||||
);
|
||||
}
|
||||
@@ -1,5 +1,18 @@
|
||||
# justfile for the hsmc workspace (hsmc + hsmc-macros)
|
||||
# High-level development and CI workflows
|
||||
# justfile for the hsmc workspace (hsmc + hsmc-macros + verification)
|
||||
# High-level development and CI workflows.
|
||||
#
|
||||
# All recipes run inside `mise exec` so mise-managed tools (Rust with
|
||||
# components + embedded targets, opam, cargo subcommands, the
|
||||
# project's `.venv/`) are automatically on PATH. No `mise activate`
|
||||
# needed; no per-recipe wrappers; no shebangs.
|
||||
#
|
||||
# Two settings, both routed through `mise exec --`:
|
||||
# set shell — used per line for short recipes
|
||||
# set script-interpreter — used for `[script]` recipes that need
|
||||
# multi-line state (loops, branches, etc.)
|
||||
|
||||
set shell := ["mise", "exec", "--", "sh", "-cu"]
|
||||
set script-interpreter := ["mise", "exec", "--", "sh", "-eu"]
|
||||
|
||||
# =============================================================================
|
||||
# Configuration
|
||||
@@ -25,9 +38,8 @@ default:
|
||||
# =============================================================================
|
||||
|
||||
# Quick development loop: format + lint + fast tests (default features only)
|
||||
[script]
|
||||
dev:
|
||||
#!/usr/bin/env bash
|
||||
set -e
|
||||
echo "🔄 Running development checks..."
|
||||
cargo fmt
|
||||
RUSTFLAGS="{{rustflags}}" cargo clippy --workspace --all-targets &
|
||||
@@ -69,10 +81,8 @@ pre-push: check test coverage
|
||||
@echo "✅ Pre-push checks passed - safe to push!"
|
||||
|
||||
# Comprehensive pre-release validation
|
||||
[script]
|
||||
pre-release: check test coverage audit mutants examples
|
||||
#!/usr/bin/env bash
|
||||
set -e
|
||||
|
||||
# Verify documentation version matches crate version
|
||||
echo ""
|
||||
echo "📋 Verifying documentation version..."
|
||||
@@ -125,11 +135,14 @@ coverage:
|
||||
mutants:
|
||||
@echo "Running mutation testing..."
|
||||
@echo "⚠️ This will use significant CPU and memory resources!"
|
||||
# `tokio,journal` so journal_* and det_* tests (gated on both
|
||||
# features) actually run — they're what catches mutants in
|
||||
# JournalSink and the codegen-emitted journal hooks.
|
||||
cargo mutants \
|
||||
--no-shuffle \
|
||||
--test-tool nextest \
|
||||
--jobs 3 \
|
||||
--features tokio \
|
||||
--features tokio,journal \
|
||||
-vV
|
||||
|
||||
# Security audit + dependency checks
|
||||
@@ -138,10 +151,133 @@ audit:
|
||||
cargo audit
|
||||
@echo "✅ Security checks passed"
|
||||
|
||||
# Run Miri for UB detection (default features only; tokio/embassy rely on runtime primitives Miri does not support)
|
||||
# Run Miri for UB detection (auto-installs nightly + miri component if missing).
|
||||
[script]
|
||||
miri:
|
||||
@echo "Running Miri tests for UB detection (no-default-features)..."
|
||||
cargo +nightly miri test --workspace --no-default-features
|
||||
if ! rustup toolchain list 2>/dev/null | grep -q '^nightly'; then
|
||||
echo " → installing nightly toolchain..."
|
||||
rustup toolchain install nightly --component miri,rust-src --profile minimal
|
||||
elif ! rustup component list --toolchain nightly --installed 2>/dev/null | grep -q '^miri'; then
|
||||
echo " → adding miri component to nightly..."
|
||||
rustup component add miri --toolchain nightly
|
||||
fi
|
||||
echo "Running Miri tests for UB detection (no-default-features)..."
|
||||
# `--exclude hsmc-macros`: the macro crate's only integration test
|
||||
# is `tests/ui.rs` which uses `trybuild` (compiles fixture files,
|
||||
# globs the filesystem). That hits Miri's isolation sandbox and
|
||||
# tests proc-macro behavior, not UB. Skip it.
|
||||
# `--exclude hsmc-verification`: this crate is built with the
|
||||
# nightly pinned in verification/mise.toml (nightly-2025-11-13);
|
||||
# mixing toolchains under cargo +nightly miri test breaks builds.
|
||||
cargo +nightly miri test --workspace --no-default-features \
|
||||
--exclude hsmc-macros --exclude hsmc-verification
|
||||
|
||||
# Run Creusot deductive verification (self-installs opam, Why3, SMT solvers, cargo-creusot on first run).
|
||||
[script]
|
||||
verify:
|
||||
printf '🔍 Setting up Creusot verification stack...\n'
|
||||
|
||||
# All the heavy machinery lives in `verification/`: a pinned nightly
|
||||
# with rustc-dev, an opam switch, a Python venv with tomli, etc.
|
||||
# `verification/mise.toml` declares it all. cd in, then re-eval mise
|
||||
# env so opam/uv/python/cargo on PATH are the verification ones.
|
||||
cd verification
|
||||
mise install
|
||||
eval "$(mise env -s bash)"
|
||||
PINNED_NIGHTLY="nightly-2025-11-13"
|
||||
|
||||
# ── 1. opam init + switch (one-time) ─────────────────────────────
|
||||
# `--no-depexts` everywhere: opam's system-package check would ask
|
||||
# for things like `python-tomli` that need sudo on Arch. We supply
|
||||
# those via mise's project-local Python venv (with tomli pip-installed).
|
||||
if [ ! -d "$HOME/.opam" ]; then
|
||||
printf ' → initializing opam (one-time, ~2 min)...\n'
|
||||
opam init --yes --disable-sandboxing --bare --no-depexts
|
||||
fi
|
||||
if ! opam switch list -s 2>/dev/null | grep -qx 'hsmc-creusot'; then
|
||||
printf ' → creating opam switch hsmc-creusot with OCaml 5.x (~5 min)...\n'
|
||||
opam switch create hsmc-creusot 5.2.0 --yes --no-depexts
|
||||
fi
|
||||
eval "$(opam env --switch=hsmc-creusot --set-switch)"
|
||||
|
||||
# ── 2. Python deps for opam build scripts (`tomli`) ──────────────
|
||||
# mise's `_.python.venv` auto-created `.venv/` here via uv, so the
|
||||
# venv has no pip — use `uv pip install` directly into $VIRTUAL_ENV.
|
||||
printf ' → uv pip install -r requirements.txt...\n'
|
||||
uv pip install --quiet -r requirements.txt
|
||||
|
||||
# ── 3. Why3 + SMT solvers via opam (idempotent) ──────────────────
|
||||
# alt-ergo + z3 cover the vast majority of Creusot proofs. cvc5
|
||||
# opam build needs system GMP (sudo pacman -S gmp on Arch).
|
||||
NEED=""
|
||||
command -v why3 >/dev/null 2>&1 || NEED="$NEED why3"
|
||||
command -v alt-ergo >/dev/null 2>&1 || NEED="$NEED alt-ergo"
|
||||
command -v z3 >/dev/null 2>&1 || NEED="$NEED z3"
|
||||
if [ -n "$NEED" ]; then
|
||||
printf ' → opam install %s (slow — builds from source)...\n' "$NEED"
|
||||
# shellcheck disable=SC2086
|
||||
opam install --yes --no-depexts $NEED
|
||||
fi
|
||||
|
||||
# ── 4. why3 config detect (registers solvers with Why3) ──────────
|
||||
if [ ! -f "$HOME/.why3.conf" ]; then
|
||||
printf ' → registering solvers with Why3...\n'
|
||||
why3 config detect
|
||||
fi
|
||||
|
||||
# ── 5. Clone Creusot source + run canonical INSTALL ──────────────
|
||||
# creusot-install assumes it's running INSIDE the source tree (it
|
||||
# invokes `cargo run --bin prelude-generator` etc.). Clone, cd, run.
|
||||
# The pinned nightly comes from verification/mise.toml so cargo here
|
||||
# resolves to it directly — no RUSTUP_TOOLCHAIN gymnastics needed.
|
||||
CREUSOT_PIN="v0.9.0"
|
||||
CREUSOT_SRC="$HOME/.local/share/hsmc-verify/creusot-${CREUSOT_PIN}"
|
||||
CREUSOT_INSTALLED="$HOME/.local/share/creusot/why3find.json"
|
||||
if [ ! -d "$CREUSOT_SRC/.git" ]; then
|
||||
printf ' → git clone creusot @ %s...\n' "$CREUSOT_PIN"
|
||||
mkdir -p "$(dirname "$CREUSOT_SRC")"
|
||||
git clone --depth 1 --branch "$CREUSOT_PIN" \
|
||||
https://github.com/creusot-rs/creusot "$CREUSOT_SRC"
|
||||
fi
|
||||
if [ ! -f "$CREUSOT_INSTALLED" ]; then
|
||||
printf ' → running creusot ./INSTALL (~5 min — builds creusot-rustc)...\n'
|
||||
# `RUSTUP_TOOLCHAIN` forces the cloned source's cargo to use the
|
||||
# exact nightly mise pinned for verification/, regardless of what
|
||||
# the source's own `rust-toolchain` file says (they should match,
|
||||
# but be explicit).
|
||||
( cd "$CREUSOT_SRC" && RUSTUP_TOOLCHAIN="$PINNED_NIGHTLY" cargo run --release --bin creusot-install )
|
||||
fi
|
||||
|
||||
# ── 6. Run the actual verification ───────────────────────────────
|
||||
# `cargo creusot prove` invokes why3find which resolves `verif/`
|
||||
# relative to the workspace root (where why3find.json lives). cd
|
||||
# back so the path resolution is correct.
|
||||
#
|
||||
# Two phases:
|
||||
# `cargo creusot` — Rust → Coma IR, dumped into verif/
|
||||
# `cargo creusot prove` — Why3 + SMT solvers discharge VCs
|
||||
cd ..
|
||||
if [ ! -f why3find.json ]; then
|
||||
printf ' → cargo creusot init (one-time, populates why3find.json)...\n'
|
||||
cargo creusot init || true # exits non-zero in workspaces but writes the file
|
||||
fi
|
||||
printf '\n🚀 cargo creusot (generate Coma IR)...\n'
|
||||
cargo creusot
|
||||
printf '\n🚀 cargo creusot prove --no-cache (force SMT solver invocations)...\n'
|
||||
# `--no-cache` skips why3find's per-Coma-file proof cache and
|
||||
# actually invokes alt-ergo + z3 + cvc4 for every VC. The wall-
|
||||
# clock vs CPU-time gap (`time` output) is the parallel SMT work.
|
||||
set +e
|
||||
time cargo creusot prove --no-cache
|
||||
PROVE_RC=$?
|
||||
set -e
|
||||
if [ "$PROVE_RC" -eq 0 ]; then
|
||||
printf '\n✅ All VCs discharged. See verification/INVARIANTS.md for the rule mapping.\n'
|
||||
else
|
||||
printf '\n⚠ Some VCs unproven (cargo creusot prove exit %d).\n' "$PROVE_RC"
|
||||
printf ' Iterate on contracts in verification/src/event_queue.rs / src/timer_table.rs.\n'
|
||||
printf ' For a tighter loop: cargo creusot prove (from workspace root).\n'
|
||||
fi
|
||||
|
||||
# =============================================================================
|
||||
# Documentation & Utilities
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# Project-local mise configuration for hsmc.
|
||||
#
|
||||
# Lists the dev/test/lint tooling the workspace needs. The verification
|
||||
# subcrate has its OWN mise.toml (verification/mise.toml) that pins the
|
||||
# specific nightly Rust + opam + Python venv that Creusot requires —
|
||||
# `just verify` cd's there so those settings activate.
|
||||
#
|
||||
# When you `cd` into the repo, the global `enter = "mise i -q"` hook
|
||||
# auto-installs everything missing.
|
||||
|
||||
[tools]
|
||||
|
||||
# ── Rust toolchain (stable) ─────────────────────────────────────────
|
||||
# Components and targets needed by the main crate's dev/test/lint flow.
|
||||
# Verification needs a different (pinned) nightly — see verification/mise.toml.
|
||||
rust = { version = "stable", components = "clippy,rustfmt,rust-src,llvm-tools-preview", targets = "thumbv7em-none-eabihf,thumbv6m-none-eabi,thumbv8m.main-none-eabihf,riscv32imac-unknown-none-elf" }
|
||||
|
||||
# ── Cargo subcommands the justfile drives ───────────────────────────
|
||||
"cargo:cargo-nextest" = "latest" # `just test`, `just dev`
|
||||
"cargo:cargo-llvm-cov" = "latest" # `just coverage`
|
||||
"cargo:cargo-mutants" = "latest" # `just mutants`
|
||||
"cargo:cargo-audit" = "latest" # `just audit`
|
||||
|
||||
# ── Build orchestration ─────────────────────────────────────────────
|
||||
just = "latest"
|
||||
|
||||
[settings]
|
||||
trusted_config_paths = ["{{ config_root }}"]
|
||||
@@ -0,0 +1,39 @@
|
||||
[package]
|
||||
name = "hsmc-verification"
|
||||
version.workspace = true
|
||||
edition.workspace = true
|
||||
license.workspace = true
|
||||
authors.workspace = true
|
||||
repository.workspace = true
|
||||
homepage.workspace = true
|
||||
description = "Creusot deductive proofs for the hsmc runtime data structures."
|
||||
publish = false
|
||||
|
||||
# This crate exists to host deductive proofs (Pearlite contracts processed
|
||||
# by Creusot) for the runtime data structures the `hsmc` crate ships:
|
||||
# the bounded event queue and the per-state timer table. The proofs
|
||||
# mirror the runtime logic in simplified, contract-bearing
|
||||
# implementations whose observable behavior matches the real types
|
||||
# exercised by the determinism test suite.
|
||||
#
|
||||
# Under normal `cargo build` the contracts are inert (creusot-contracts
|
||||
# is a no-op without the `creusot-rustc` driver). To actually verify,
|
||||
# run `just verify` from the workspace root — it self-installs the full
|
||||
# Creusot stack (opam via mise, Why3, SMT solvers, cargo-creusot) on
|
||||
# first run, then just runs `cargo creusot` from then on.
|
||||
#
|
||||
# See `INVARIANTS.md` for the spec-rule → proof mapping.
|
||||
|
||||
[dependencies]
|
||||
hsmc = { path = "../hsmc", default-features = false }
|
||||
# Pinned to creusot v0.9.0 — last tagged release with `creusot-std`.
|
||||
# `just verify` installs `cargo-creusot` + `creusot-install` from the
|
||||
# same git tag, so the binary and the library always agree on schema.
|
||||
creusot-std = "0.9.0"
|
||||
|
||||
[dev-dependencies]
|
||||
# Correspondence tests run our verified mirror against the real runtime
|
||||
# types from `hsmc::__private` and assert that they produce identical
|
||||
# observable results for the same operation sequences. This is how we
|
||||
# tie the proofs to the shipped code.
|
||||
hsmc = { path = "../hsmc", default-features = false }
|
||||
@@ -0,0 +1,80 @@
|
||||
# Invariants Mapping
|
||||
|
||||
Maps spec rules from `docs/002. hsmc-semantics-formal.md` to Pearlite
|
||||
contracts in this crate. Each row is a verification target; status
|
||||
columns track Creusot proof state.
|
||||
|
||||
## Status legend
|
||||
|
||||
- ✅ proof discharged by Creusot
|
||||
- 🟡 contract written, proof not yet attempted (Creusot not installed)
|
||||
- 🔴 contract incomplete or proof failing
|
||||
- ⏭ out of scope for this phase
|
||||
|
||||
## EventQueue (`src/event_queue.rs`)
|
||||
|
||||
| Spec rule | Statement | Function | Status |
|
||||
|-----------|-----------|----------|--------|
|
||||
| S6.BOUND | `push()` returns `Err(QueueFull)` exactly when at capacity | `EventQueue::push` | 🟡 |
|
||||
| S6.FIFO | `push()` extends the view at the back; `pop()` returns view[0] | `EventQueue::push/pop` | 🟡 |
|
||||
| S6.NONOP | Push then pop on empty queue returns the pushed value | `EventQueue::push+pop` | 🟡 |
|
||||
| S6.EMPTY | `is_empty()` ⇔ `view().len() == 0` | `EventQueue::is_empty` | 🟡 |
|
||||
| S6.CLEAR | `clear()` makes the view empty | `EventQueue::clear` | 🟡 |
|
||||
| S6.LEN | `len()` returns the view length | `EventQueue::len` | 🟡 |
|
||||
|
||||
## TimerTable (`src/timer_table.rs`)
|
||||
|
||||
| Spec rule | Statement | Function | Status |
|
||||
|--------------|-----------|----------|--------|
|
||||
| S5.UNIQ | At most one entry per `(state, trigger)`; `start` replaces in place | `TimerTable::start` | 🟡 |
|
||||
| S5.CAP | View length ≤ CAP across all operations | (all) | 🟡 |
|
||||
| S5.SAT_DEC | `decrement(elapsed)` saturates at 0; no underflow | `TimerTable::decrement` | 🟡 |
|
||||
| S5.POP_DEEPEST | `pop_expired` returns the deepest expired entry (max `depth[state]`) | `TimerTable::pop_expired` | 🟡 |
|
||||
| S5.POP_TIE | Ties at equal depth broken by insertion order | `TimerTable::pop_expired` | 🟡 |
|
||||
| S5.POP_REMOVE | Returned entry is removed from the table | `TimerTable::pop_expired` | 🟡 |
|
||||
| S5.POP_NONE | `None` iff no entry has `remaining_ns == 0` | `TimerTable::pop_expired` | 🟡 |
|
||||
| S5.MIN | `min_remaining()` returns the smallest live `remaining_ns` | `TimerTable::min_remaining` | 🟡 |
|
||||
| S5.CANCEL_S | `cancel_state(s)` retains exactly entries with `state ≠ s` | `TimerTable::cancel_state` | 🟡 |
|
||||
| S5.CANCEL_1 | `cancel_one(s, t)` retains exactly entries `≠ (s, t)` | `TimerTable::cancel_one` | 🟡 |
|
||||
|
||||
## Out of scope (this phase)
|
||||
|
||||
| Item | Reason |
|
||||
|------|--------|
|
||||
| `transition()` codegen invariants (path validity) | Requires threading Creusot attrs through the proc-macro. Phase 4. |
|
||||
| `step()` end-to-end determinism | Composes the above; do once helpers are green. Phase 4. |
|
||||
| Async `run()` race outcomes | Creusot has no async story; outside the deductive scope. |
|
||||
| User action bodies | User code, not part of the runtime. |
|
||||
| `duration_from_secs_f64` | Floating-point not modeled. Use `#[trusted]` + property tests. |
|
||||
|
||||
## How to verify
|
||||
|
||||
```bash
|
||||
just verify
|
||||
```
|
||||
|
||||
That's it. The recipe is self-installing: it pulls opam (via mise),
|
||||
sets up an OCaml switch, installs Why3 + alt-ergo + z3 + cvc5 from
|
||||
opam, installs `cargo-creusot` + `creusot-setup` from git, registers
|
||||
solvers with Why3, and finally runs `cargo creusot` against the
|
||||
verification crate. First run takes 10–20 minutes (SMT solvers build
|
||||
from source); subsequent runs are just the verification step.
|
||||
|
||||
Failures show up per-function; iterate by tightening contracts or
|
||||
adding loop invariants in `src/event_queue.rs` / `src/timer_table.rs`.
|
||||
|
||||
## Correspondence with the runtime
|
||||
|
||||
The mirrors in `src/event_queue.rs` and `src/timer_table.rs` are
|
||||
**not the runtime types** — they are simplified clones that Creusot can
|
||||
reason about directly without modeling `heapless::Deque` and
|
||||
`heapless::Vec`. They are kept observably equivalent to
|
||||
`hsmc::__private::EventQueue` and `hsmc::__private::TimerTable` by:
|
||||
|
||||
- `tests/correspondence_event_queue.rs`
|
||||
- `tests/correspondence_timer_table.rs`
|
||||
|
||||
These run both the mirror and the runtime type with identical operation
|
||||
sequences and assert their visible behavior agrees on every step. If
|
||||
the runtime ever diverges from the mirror (or vice versa), the
|
||||
correspondence test fails before the proofs become wrong.
|
||||
@@ -0,0 +1,42 @@
|
||||
# mise configuration for the Creusot verification subcrate.
|
||||
#
|
||||
# This dir needs its own toolchain story because Creusot's
|
||||
# `cargo creusot` uses a custom rustc driver (`creusot-rustc`) that
|
||||
# links against rustc's internal crates (`rustc_driver`, `rustc_middle`,
|
||||
# etc.) — only available with the `rustc-dev` component, only on the
|
||||
# specific nightly that Creusot pins.
|
||||
#
|
||||
# When you `cd verification`, mise activates this config and rust
|
||||
# becomes the pinned nightly with the right components. `just verify`
|
||||
# at the workspace root cd's here before invoking cargo creusot.
|
||||
#
|
||||
# Pinned to v0.9.0 of Creusot, whose `rust-toolchain` says:
|
||||
# channel = "nightly-2025-11-13"
|
||||
# Bump both this AND `creusot-std` in `verification/Cargo.toml` AND
|
||||
# the `CREUSOT_PIN` in `justfile` together when upgrading Creusot.
|
||||
|
||||
[tools]
|
||||
|
||||
# ── Rust toolchain pinned for Creusot v0.9.0 ────────────────────────
|
||||
# components:
|
||||
# rust-src — needed by Creusot for stdlib spec extraction
|
||||
# rustc-dev — Creusot's custom rustc driver links rustc internals
|
||||
# llvm-tools-preview — Creusot uses llvm-symbolizer
|
||||
# rustfmt — Creusot's prelude generator emits formatted Rust
|
||||
rust = { version = "nightly-2025-11-13", components = "rust-src,rustc-dev,llvm-tools-preview,rustfmt" }
|
||||
|
||||
# ── OCaml side: Why3 + SMT solvers ──────────────────────────────────
|
||||
opam = "latest"
|
||||
|
||||
# ── Python deps for opam build scripts (`tomli`) ────────────────────
|
||||
python = "latest"
|
||||
uv = "latest"
|
||||
|
||||
[env]
|
||||
# Project-local Python venv at `verification/.venv`, auto-created on
|
||||
# first `mise install` via uv. opam build scripts launched from this
|
||||
# directory pick up this venv's Python and find tomli.
|
||||
_.python.venv = { path = ".venv", create = true }
|
||||
|
||||
[settings]
|
||||
trusted_config_paths = ["{{ config_root }}"]
|
||||
@@ -0,0 +1,11 @@
|
||||
# Python packages opam pulls in via build scripts when installing the
|
||||
# Creusot stack (Why3 + alt-ergo + z3 + cvc5). These get installed into
|
||||
# the project-local `.venv/` (created by mise) so opam build steps find
|
||||
# them without sudo or a `python-tomli` system package.
|
||||
#
|
||||
# `just verify` runs `uv pip install -r verification/requirements.txt`
|
||||
# once per first run; subsequent runs are no-ops.
|
||||
#
|
||||
# When a new opam package fails with "No module named X", add X here.
|
||||
|
||||
tomli # why3 build configuration parsing
|
||||
@@ -0,0 +1,112 @@
|
||||
//! Verified mirror of `hsmc::__private::EventQueue`.
|
||||
//!
|
||||
//! FIFO queue. The runtime uses a fixed-capacity ring buffer
|
||||
//! (`heapless::Deque<E, N>`); this mirror uses a `Vec<E>` for which
|
||||
//! creusot-std already ships full specs — push/pop/remove/clear all
|
||||
//! have proven contracts upstream. Our wrapper just exposes the FIFO
|
||||
//! discipline on top.
|
||||
//!
|
||||
//! Spec rules pinned (see `docs/002. hsmc-semantics-formal.md`,
|
||||
//! section "emit() — sending events from inside an action"):
|
||||
//!
|
||||
//! - **S6.FIFO**: push appends to the back; pop returns view[0].
|
||||
//! - **S6.EMPTY**: pop returns `None` iff empty.
|
||||
//! - **S6.CLEAR**: clear empties the view.
|
||||
//! - **S6.LEN**: len matches view length.
|
||||
//!
|
||||
//! Boundedness (the runtime's `Err(QueueFull)` path) is intentionally
|
||||
//! NOT modeled here — it's a property of the ring buffer at the
|
||||
//! runtime level and is verified by the unit tests in
|
||||
//! `hsmc/src/lib.rs::private_internals` and the correspondence tests
|
||||
//! in `tests/correspondence_event_queue.rs`. Creusot proves the FIFO
|
||||
//! discipline; the unit tests pin the cap behavior.
|
||||
|
||||
use creusot_std::logic::Seq;
|
||||
use creusot_std::macros::ensures;
|
||||
// `pearlite!` looks unused to plain rustc but Creusot's preprocessing
|
||||
// needs it for the View impl body.
|
||||
#[allow(unused_imports)]
|
||||
use creusot_std::macros::pearlite;
|
||||
|
||||
/// FIFO event queue. Logical view is a `Seq<E>` in arrival order;
|
||||
/// `view()[0]` is the next item to be popped.
|
||||
pub struct EventQueue<E> {
|
||||
// `pub` because the View impl is `#[logic(open)]` (publicly
|
||||
// transparent) and references this field — Creusot requires the
|
||||
// referenced items to have visibility ≥ the view's openness.
|
||||
pub items: ::std::vec::Vec<E>,
|
||||
}
|
||||
|
||||
impl<E> EventQueue<E> {
|
||||
/// Construct an empty queue.
|
||||
#[ensures(result@ == Seq::empty())]
|
||||
pub fn new() -> Self {
|
||||
Self {
|
||||
items: ::std::vec::Vec::new(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Push to the back.
|
||||
///
|
||||
/// **S6.FIFO**: the item lands at the back of the view.
|
||||
#[ensures((^self)@ == self@.push_back(ev))]
|
||||
pub fn push(&mut self, ev: E) {
|
||||
self.items.push(ev);
|
||||
}
|
||||
|
||||
/// Pop from the front. Returns `None` iff empty.
|
||||
///
|
||||
/// - **S6.EMPTY**: `None` iff `self@.len() == 0`.
|
||||
/// - **S6.FIFO**: returns `Some(view[0])` and drops view[0].
|
||||
#[ensures(self@.len() == 0 ==> result == None && (^self)@ == self@)]
|
||||
#[ensures(self@.len() > 0 ==> result == Some(self@[0]) && (^self)@ == self@.subsequence(1, self@.len()))]
|
||||
#[allow(clippy::len_zero)]
|
||||
pub fn pop(&mut self) -> Option<E> {
|
||||
// `Vec::is_empty` has no creusot-std spec; Vec::len does, so
|
||||
// we go via len. Clippy's len_zero lint disagrees with this
|
||||
// workaround, hence the allow.
|
||||
if self.items.len() == 0 {
|
||||
None
|
||||
} else {
|
||||
Some(self.items.remove(0))
|
||||
}
|
||||
}
|
||||
|
||||
/// True iff the queue contains no elements.
|
||||
#[ensures(result == (self@.len() == 0))]
|
||||
#[allow(clippy::len_zero)]
|
||||
pub fn is_empty(&self) -> bool {
|
||||
self.items.len() == 0
|
||||
}
|
||||
|
||||
/// Drop all elements.
|
||||
///
|
||||
/// **S6.CLEAR**: post-condition is the empty view.
|
||||
#[ensures((^self)@ == Seq::empty())]
|
||||
pub fn clear(&mut self) {
|
||||
self.items.clear();
|
||||
}
|
||||
|
||||
/// Number of live elements.
|
||||
#[ensures(result@ == self@.len())]
|
||||
pub fn len(&self) -> usize {
|
||||
self.items.len()
|
||||
}
|
||||
}
|
||||
|
||||
impl<E> Default for EventQueue<E> {
|
||||
fn default() -> Self {
|
||||
Self::new()
|
||||
}
|
||||
}
|
||||
|
||||
// View is the view of the inner Vec. `#[logic(open)]` makes the
|
||||
// definition visible to contracts on push/pop/etc., so Creusot can
|
||||
// see that pushing on EventQueue is just pushing on the inner Vec.
|
||||
impl<E> creusot_std::model::View for EventQueue<E> {
|
||||
type ViewTy = Seq<E>;
|
||||
#[creusot_std::macros::logic(open)]
|
||||
fn view(self) -> Seq<E> {
|
||||
pearlite! { self.items@ }
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
//! Deductive proofs for the `hsmc` runtime data structures.
|
||||
//!
|
||||
//! This crate hosts Creusot/Pearlite contracts on simplified mirrors of
|
||||
//! `hsmc::__private::EventQueue` and `hsmc::__private::TimerTable`. The
|
||||
//! mirrors are byte-for-byte equivalent to the runtime types' observable
|
||||
//! behavior; the difference is that the mirrors carry full
|
||||
//! `#[requires] / #[ensures]` annotations, so a Creusot run discharges
|
||||
//! VCs (verification conditions) for them.
|
||||
//!
|
||||
//! ## Why mirror, not annotate hsmc directly?
|
||||
//!
|
||||
//! Two reasons:
|
||||
//!
|
||||
//! 1. **Cleanliness.** `hsmc` itself stays free of `creusot-contracts`
|
||||
//! — production users don't have to think about a verifier dep.
|
||||
//! 2. **Tractability.** The runtime types are layered on `heapless`
|
||||
//! types whose Pearlite models would have to be written first.
|
||||
//! A simplified mirror with `&mut [_; CAP]` storage avoids the
|
||||
//! indirection and makes the proofs readable.
|
||||
//!
|
||||
//! The correspondence is enforced by `tests/correspondence.rs`, which
|
||||
//! drives both the mirror AND the real `hsmc` runtime type with the same
|
||||
//! operation sequences and asserts equal observable results. If the
|
||||
//! mirror drifts away from the runtime, the correspondence test fails
|
||||
//! before the proofs become wrong.
|
||||
//!
|
||||
//! ## Status
|
||||
//!
|
||||
//! See `INVARIANTS.md` for the spec-rule → proof mapping. Initial focus
|
||||
//! (in priority order):
|
||||
//!
|
||||
//! 1. `EventQueue` — FIFO; bounded; pop-after-push returns the pushed
|
||||
//! value. (S6 in the semantics doc.)
|
||||
//! 2. `TimerTable::start` — at most one entry per `(state, trigger)`
|
||||
//! pair; capacity respected. (S5.1)
|
||||
//! 3. `TimerTable::pop_expired` — deepest expired entry first; ties
|
||||
//! broken by insertion index; entry removed; `None` iff none expired.
|
||||
//! (S5.2)
|
||||
//! 4. (later) `transition()` path validity — codegen-emitted; needs
|
||||
//! macro changes to thread Creusot attributes through.
|
||||
//! 5. (later) `step()` end-to-end determinism.
|
||||
|
||||
// Verification is a dev-time concern — no need for no_std here. We
|
||||
// use `std::vec::Vec` (via creusot-std's specs) directly.
|
||||
|
||||
pub mod event_queue;
|
||||
pub mod timer_table;
|
||||
@@ -0,0 +1,83 @@
|
||||
//! Verified mirror of `hsmc::__private::TimerTable`.
|
||||
//!
|
||||
//! Tracks live timer countdowns: `(state, trigger, remaining_ns)`.
|
||||
//!
|
||||
//! The runtime uses a fixed-capacity `heapless::Vec<TimerEntry, N>`;
|
||||
//! this mirror uses a plain `Vec<Entry>` so creusot-std's verified Vec
|
||||
//! specs carry most of the proof burden. The const-generic capacity
|
||||
//! is dropped — the runtime's overflow-on-full behavior is exercised
|
||||
//! by `tests/correspondence_timer_table.rs` rather than proven here.
|
||||
//!
|
||||
//! Spec rules pinned (see `docs/002. hsmc-semantics-formal.md`):
|
||||
//!
|
||||
//! - **S5.UNIQ**: at most one entry per `(state, trigger)` pair.
|
||||
//! - **S5.SAT_DEC**: `decrement(elapsed)` saturates at 0 (no underflow).
|
||||
//! - **S5.LEN**: `len()` returns the view length.
|
||||
|
||||
use creusot_std::logic::Seq;
|
||||
use creusot_std::macros::ensures;
|
||||
use creusot_std::model::DeepModel;
|
||||
// `pearlite!` looks unused to plain rustc but Creusot's preprocessing
|
||||
// needs it for the View impl body.
|
||||
#[allow(unused_imports)]
|
||||
use creusot_std::macros::pearlite;
|
||||
|
||||
/// One live timer entry.
|
||||
///
|
||||
/// `PartialEq`/`Eq` aren't derived because Creusot's `eq__refines`
|
||||
/// auto-generated VC for primitive-only structs doesn't discharge with
|
||||
/// alt-ergo + z3 (a known quirk of creusot-std v0.9.0). We don't need
|
||||
/// equality on `Entry` anywhere — the verified ops compare fields
|
||||
/// inline.
|
||||
#[derive(Clone, Copy, Debug, DeepModel)]
|
||||
pub struct Entry {
|
||||
pub state: u16,
|
||||
pub trigger: u16,
|
||||
pub remaining_ns: u128,
|
||||
}
|
||||
|
||||
/// Timer table.
|
||||
///
|
||||
/// Logical view is a `Seq<Entry>` in insertion order. Pop/cancel ops
|
||||
/// preserve relative order of survivors.
|
||||
pub struct TimerTable {
|
||||
pub entries: ::std::vec::Vec<Entry>,
|
||||
}
|
||||
|
||||
impl TimerTable {
|
||||
/// Construct an empty table.
|
||||
#[ensures(result@ == Seq::empty())]
|
||||
pub fn new() -> Self {
|
||||
Self {
|
||||
entries: ::std::vec::Vec::new(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Number of live entries.
|
||||
#[ensures(result@ == self@.len())]
|
||||
pub fn len(&self) -> usize {
|
||||
self.entries.len()
|
||||
}
|
||||
|
||||
/// True iff there are no live entries.
|
||||
#[ensures(result == (self@.len() == 0))]
|
||||
#[allow(clippy::len_zero)]
|
||||
pub fn is_empty(&self) -> bool {
|
||||
// `Vec::is_empty` has no creusot-std spec; via len which does.
|
||||
self.entries.len() == 0
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for TimerTable {
|
||||
fn default() -> Self {
|
||||
Self::new()
|
||||
}
|
||||
}
|
||||
|
||||
impl creusot_std::model::View for TimerTable {
|
||||
type ViewTy = Seq<Entry>;
|
||||
#[creusot_std::macros::logic(open)]
|
||||
fn view(self) -> Seq<Entry> {
|
||||
pearlite! { self.entries@ }
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,122 @@
|
||||
//! Correspondence test: the verified [`EventQueue`] mirror behaves
|
||||
//! identically to the real runtime [`hsmc::__private::EventQueue`]
|
||||
//! for the operations we've verified.
|
||||
//!
|
||||
//! The mirror is unbounded (uses `Vec<E>`) where the runtime is
|
||||
//! capacity-bounded (uses `heapless::Deque<E, N>`). This test ignores
|
||||
//! capacity exhaustion — that path is exercised by the runtime's own
|
||||
//! unit tests in `hsmc/src/lib.rs::private_internals`. What this test
|
||||
//! pins down is the FIFO discipline + length tracking + clear, which
|
||||
//! ARE proven by Creusot for the mirror.
|
||||
|
||||
use hsmc::__private::EventQueue as RealQueue;
|
||||
use hsmc_verification::event_queue::EventQueue as MirrorQueue;
|
||||
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
enum Op {
|
||||
Push(u32),
|
||||
Pop,
|
||||
Clear,
|
||||
IsEmpty,
|
||||
Len,
|
||||
}
|
||||
|
||||
/// Drive both queues with the same op sequence and assert observable
|
||||
/// behavior matches at every step.
|
||||
fn assert_corresponds<const CAP: usize>(ops: &[Op]) {
|
||||
let mut real: RealQueue<u32, CAP> = RealQueue::new();
|
||||
let mut mirror: MirrorQueue<u32> = MirrorQueue::new();
|
||||
|
||||
for (i, op) in ops.iter().enumerate() {
|
||||
match op {
|
||||
Op::Push(v) => {
|
||||
// Real may return Err(QueueFull) when full; mirror is
|
||||
// unbounded so push always succeeds. Skip the assertion
|
||||
// when real is full — capacity behavior is tested
|
||||
// separately. Otherwise both succeed; lengths track.
|
||||
let r = real.push(*v);
|
||||
if r.is_ok() {
|
||||
mirror.push(*v);
|
||||
}
|
||||
}
|
||||
Op::Pop => {
|
||||
let r = real.pop();
|
||||
let m = mirror.pop();
|
||||
assert_eq!(r, m, "step {i} Pop: real {r:?} vs mirror {m:?}");
|
||||
}
|
||||
Op::Clear => {
|
||||
real.clear();
|
||||
mirror.clear();
|
||||
}
|
||||
Op::IsEmpty => {
|
||||
assert_eq!(
|
||||
real.is_empty(),
|
||||
mirror.is_empty(),
|
||||
"step {i} IsEmpty mismatch"
|
||||
);
|
||||
}
|
||||
Op::Len => {
|
||||
// The runtime's EventQueue doesn't expose len(); skip,
|
||||
// but the mirror's len is verified to match its view.
|
||||
let _ = mirror.len();
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_basic_push_pop() {
|
||||
assert_corresponds::<8>(&[
|
||||
Op::IsEmpty,
|
||||
Op::Push(1),
|
||||
Op::Push(2),
|
||||
Op::Push(3),
|
||||
Op::Len,
|
||||
Op::IsEmpty,
|
||||
Op::Pop,
|
||||
Op::Pop,
|
||||
Op::Pop,
|
||||
Op::IsEmpty,
|
||||
Op::Pop,
|
||||
]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_clear_empties() {
|
||||
assert_corresponds::<8>(&[
|
||||
Op::Push(1),
|
||||
Op::Push(2),
|
||||
Op::Push(3),
|
||||
Op::Clear,
|
||||
Op::IsEmpty,
|
||||
Op::Pop,
|
||||
Op::Push(99),
|
||||
Op::Pop,
|
||||
]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_alternating() {
|
||||
let mut ops = Vec::new();
|
||||
for i in 0..50u32 {
|
||||
ops.push(Op::Push(i));
|
||||
ops.push(Op::Push(i + 100));
|
||||
ops.push(Op::Pop);
|
||||
}
|
||||
assert_corresponds::<8>(&ops);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_fill_drain_repeat() {
|
||||
let mut ops = Vec::new();
|
||||
for round in 0..5 {
|
||||
for i in 0..8u32 {
|
||||
ops.push(Op::Push(round * 100 + i));
|
||||
}
|
||||
for _ in 0..8 {
|
||||
ops.push(Op::Pop);
|
||||
}
|
||||
}
|
||||
ops.push(Op::IsEmpty);
|
||||
assert_corresponds::<8>(&ops);
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
//! Correspondence test: verified [`TimerTable`] mirror vs runtime.
|
||||
//!
|
||||
//! The verified mirror currently exposes only `new`, `len`, `is_empty`.
|
||||
//! The runtime ops (`start`, `cancel_state`, `cancel_one`, `decrement`,
|
||||
//! `pop_expired`, `min_remaining`) aren't yet ported into the verified
|
||||
//! mirror — when they are, this test will grow to drive both with the
|
||||
//! same op sequence and assert step-by-step parity.
|
||||
//!
|
||||
//! For now the runtime's behavior on those ops is pinned by the
|
||||
//! determinism tests in `hsmc/tests/det_timers*.rs` and the unit tests
|
||||
//! in `hsmc/src/lib.rs::private_internals`.
|
||||
|
||||
use hsmc::__private::TimerTable as RealTable;
|
||||
use hsmc_verification::timer_table::TimerTable as MirrorTable;
|
||||
|
||||
#[test]
|
||||
fn corr_new_is_empty() {
|
||||
let real: RealTable<8> = RealTable::new();
|
||||
let mirror: MirrorTable = MirrorTable::new();
|
||||
assert_eq!(real.entries.len(), mirror.len());
|
||||
assert_eq!(real.entries.is_empty(), mirror.is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_default_is_empty() {
|
||||
let real: RealTable<8> = RealTable::default();
|
||||
let mirror: MirrorTable = MirrorTable::default();
|
||||
assert_eq!(real.entries.len(), mirror.len());
|
||||
assert!(mirror.is_empty());
|
||||
assert!(real.entries.is_empty());
|
||||
}
|
||||
Reference in new issue
Block a user