hsmc/docs/004. unsafe-safety-contract.md

Unsafe Safety Contract

This document inventories every unsafe block emitted by the statechart! macro, states the preconditions, names what establishes them, and lists the layered checks that prove they hold.

It is the answer to "you said no unsafe — now there's unsafe. How do I know it's correct?".

Inventory

All unsafe lives in code emitted by hsmc-macros. The runtime hsmc crate, the user's chart definition, and the user's action / during bodies contain none.

The blocks are six index-elision sites in five generated functions, each pairing a slice::get_unchecked (or Option::unwrap_unchecked, in earlier passes — currently none) with a documented bound.

Site	Index expression	Bound
step() — sync + async — __DISPATCH lookup	cur * N_EVENTS + ev_id	< __DISPATCH.len() = N * N_EVENTS
apply_path() — sync + async — __PATH_RANGE	from * N_STATES + target	< __PATH_RANGE.len() = N * N
apply_path() — sync + async — __PATH_DATA[s..m]	s..m from __PATH_RANGE[idx]	s ≤ m ≤ __PATH_DATA.len()
apply_path() — sync + async — __PATH_DATA[m..e]	m..e from __PATH_RANGE[idx]	m ≤ e ≤ __PATH_DATA.len()
follow_defaults() — sync + async — __DEFAULT_CHILD	cur	< __DEFAULT_CHILD.len() = N_STATES
do_terminate() — sync + async — __TERMINATE_RANGE + __TERMINATE_DATA[s..e]	cur, s..e	cur < N_STATES; s ≤ e ≤ __TERMINATE_DATA.len()

N here is the number of declared states, N_EVENTS the number of declared event variants. Both are codegen constants per chart.

Preconditions

The bounds above reduce to two families of fact:

P1 — State-id well-formedness. Every u16 value that ends up in self.current (and so feeds the cur index above) is one of:

• 0 (root entry on cold start, see enter_path(0)),
• the target slot of a __DISPATCH entry (handler resolution),
• a __DEFAULT_CHILD[cur] value (default-chain descent),
• a Some(t) from __PATH_DATA (apply_path's enter loop),
• a target: u16 parameter to transition().

All five sources are produced by codegen from IR::states, whose StateIr.id field is 0..N_STATES by construction (ir::build_ir assigns ids by enumeration; ir::resolve_transitions only resolves identifiers to existing entries; validate::validate rejects duplicates and unresolvable names). User code cannot write self.current — the field is private, the chart context is the only field handed to action bodies, and the action context's __terminated: &bool reference is read-only.

P2 — Range-table well-formedness. For every (from, to) pair the codegen-emitted __PATH_RANGE[from * N + to] = (s, m, e) triple satisfies 0 ≤ s ≤ m ≤ e ≤ __PATH_DATA.len(). The same holds for __TERMINATE_RANGE[i] = (s, e) against __TERMINATE_DATA. The triple's interpretation is: exit chain is __PATH_DATA[s..m], enter chain is __PATH_DATA[m..e]. Both slices are required to fit inside __PATH_DATA.

Codegen establishes P2 in compute_transition_paths (codegen.rs ~133): every emitted offset is a usize cursor into a Vec<u16> that is grown only by push, so the cursor never exceeds the length, and the triple is recorded after both halves of the chain are pushed.

Verification — five overlapping checks

Each check covers a different failure mode. The unsafe surface is secure when all five pass.

1. Compile-time const-eval (build error)

Every generated chart contains a const _: () = { ... } block (codegen.rs ~2465) that re-states P2 as assert!s evaluated at type check time. A codegen change that emits a malformed (s, m, e) trips a rustc E0080: evaluation panicked: diagnostic before any runtime code is produced.

Verified: manually injecting (s=0, m=99, e=99) into a 4-element __PATH_DATA produces

error[E0080]: evaluation panicked: __PATH_RANGE: e past __PATH_DATA end

so the assert is live, not optimized away.

2. Runtime debug_assert! companions

Every unsafe { ... get_unchecked ... } is paired with a debug_assert! of the same predicate (codegen.rs ~2693, ~2978–2987, ~3110, ~3211). debug_assert! is a #[cfg(debug_assertions)] no-op in --release, so production code pays nothing. In dev/test it panics with a clear message before the unsafe access runs.

Coverage: every dispatch through any of the 68 hsmc behavior tests exercises the relevant assertions. A regression in P1 (e.g., a codegen change that lets a stale id leak into self.current) panics the test, naming the violated bound.

3. Miri (UB detection)

cargo +nightly miri test -p hsmc runs the test suite under Miri, the Rust UB interpreter. Miri detects out-of-bounds reads/writes, use-after-free, and other unsafe-related UB.

Status: 20 unit + 46 behavior tests pass under Miri with the current unsafe set.

4. Mutation testing (test-coverage proof)

cargo mutants flips operators / removes branches in the hsmc-macros codegen and hsmc/src/lib.rs runtime, rebuilding and testing each mutant. Run with --features hsmc/tokio,hsmc/journal --test-package hsmc so the integration tests in hsmc/tests/ (which are gated on those features) actually compile and run; without that, cargo-mutants restricts to the per-package test set and the asymmetric-depth lateral tests don't fire.

Status (with the correct invocation):

• hsmc-macros/src/codegen.rs safety-relevant fns (compute_transition_paths, compute_terminate_paths, compute_event_dispatch): 51 of 53 covered (14 caught + 37 unviable + 2 missed). The 37 unviable are mutations that don't compile in their context — the type system rejects them, which is a stronger form of "caught". The 2 missed are equivalent mutants analyzed below.
• hsmc/src/lib.rs (runtime): 48 of 48 covered (45 caught + 3 unviable + 0 missed) — full coverage.

Combined: 99 of 101 mutants accounted for (98%). Run with just safety.

The two equivalent mutants

Both produce identical __PATH_RANGE / __PATH_DATA output and therefore cannot be distinguished by any behavior test, however detailed.

Equivalent mutant 1. codegen.rs:140: while da > db { ... } → while da >= db { ... }.

The mutated loop walks a one extra step when da == db. The next loop (while db > da) then walks b up by one to compensate, and the third loop (while a != b) drives both legs to the same LCA. parent(root) = None and the ? operator short-circuit so going "past root" is symmetric on both sides. Result: same LCA, same exit/enter paths. Verified by hand on lateral, up-transition, and asymmetric-depth (4↔2) cases.

Equivalent mutant 2. codegen.rs:169: from != to && is_strict_ancestor(to, from) → from == to && is_strict_ancestor(to, from).

is_strict_ancestor(to, from) is always false when from == to (a state is not a strict ancestor of itself), so the mutated condition is always false and the up-transition branch becomes unreachable. Up-transitions fall through to the lateral branch, which computes lca(from, to) = to (since to is an ancestor of from); the lateral exit loop then walks source up to (exclusive of) to, and the enter loop breaks immediately on Some(to) == Some(to) returning an empty enter path. Result: same exit path, same empty enter path — same (s, m, e) triple.

5. Creusot-verified path-table validator + per-chart const-eval

hsmc-verification/src/paths.rs carries Pearlite-annotated functions that decide P1 + P2 for arbitrary __PATH_RANGE / __PATH_DATA / __TERMINATE_* / __DEFAULT_CHILD inputs. Each function's #[ensures(... forall ...)] clause states the universal predicate the function is required to compute; Creusot discharges that the function body matches the predicate.

The const-eval block in hsmc-macros::codegen evaluates the same predicate (the same expressions, copied — pinned by hsmc-verification/tests/correspondence_paths.rs) on every user chart's actual emitted tables at build time. Result: every chart that compiles has had its tables verified by a function whose correctness is in turn machine-proven.

This is operationally equivalent to a universal proof for end users. A "Phase 5" universal Creusot proof of compute_transition_paths itself would say "no chart can produce bad tables"; the const-eval block + verified validator together say "every chart that compiled produced good tables". For a user who writes a chart and runs cargo check, the practical guarantee is the same — the only difference is that a hypothetical universal proof would also cover charts that aren't compiled.

What's still 🟡 (verification in progress, not yet discharged):

• EventQueue operations
• TimerTable operations
• paths.rs validator functions (waiting on a just verify run)

What's still ⏭ (Phase 5):

• Universal proof of compute_transition_paths itself — would require modeling the tree structure (parent / depth invariants) in Pearlite. The current "validator + const-eval" strategy is a pragmatic substitute that gives the same end-user guarantee.

Track + run:

just verify    # full Creusot run; first run installs SMT solvers
just safety    # const-eval + debug_assert + miri + mutants in one shot

Failure modes the checks together rule out

Failure	Caught by
Codegen emits triple with s > m, m > e, e > len	(1) const-eval at build time
Codegen emits state id ≥ N_STATES in path data	(1) const-eval at build time
Runtime mutates self.current to garbage	not possible — field is private; no API path writes a garbage value
User action sets terminated	not possible — &bool borrow is read-only
Future change introduces an unsafe path bypass	(2) debug_assert in tests, (3) miri, (4) mutants
Subtle UB in a non-bounds dimension (aliasing, etc.)	(3) miri

What's not yet covered

• Universal proof of compute_transition_paths. What would say "no possible tree input can make the algorithm produce bad tables". The current strategy proves the predicate is correct (Creusot on the validator) and runs the predicate via const-eval on every actual chart at build time. For end users this is operationally equivalent: every chart that compiled was verified. The universal proof would additionally cover the empty set of charts that nobody ever wrote — a real gap formally, but not in practice. Tracked as Phase 5 in verification/INVARIANTS.md.

The previous version of this section listed:

• "Asymmetric-depth lateral transitions in tests" — that was a misdiagnosis. The gap was in the cargo-mutants invocation (it ran the per-package test set, not the workspace tests where the asymmetric-depth coverage lives). Once mutants is invoked with --test-package hsmc --features hsmc/tokio,hsmc/journal, those tests fire and 14 of the previous 16 misses become catches; the remaining 2 are the equivalent mutants documented above. Closed.
• "Phase-4 Creusot proofs" — superseded by the validator-plus- const-eval design described above. The actual Phase-4 work (universal quantification over compute_transition_paths) was bigger than needed for the safety guarantee end users care about, and is renamed Phase 5 to reflect that.

Maintenance rules

When adding a new unsafe block in codegen:

1. Express the safety predicate as a debug_assert! immediately above the unsafe { ... }.
2. If the predicate is over a static table, extend the const-eval block to cover it — this catches the worst class of bugs at build time.
3. Re-run cargo +nightly miri test -p hsmc and cargo mutants -p hsmc-macros -F <function-name> to check coverage.
4. Update this doc. The inventory above must list every unsafe block; if the table goes stale the safety story stops being auditable.