fsm.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: MIT
#ifndef FSM_FSM_HPP
#define FSM_FSM_HPP
 
#define FSM_VERSION_MAJOR 0
#define FSM_VERSION_MINOR 4
#define FSM_VERSION_PATCH 1
/*
 * Feature gating. Under ESP-IDF, Kconfig options CONFIG_FSM_* (see the
 * component's Kconfig file) drive the FSM_ENABLE_* macros via sdkconfig.h.
 * On other platforms the macros can be predefined by the build system
 * (the CMake options FSM_OBSERVER / FSM_INTROSPECTION do so) and default on.
 */
#if defined(ESP_PLATFORM)
#  include "sdkconfig.h"
#  ifndef FSM_ENABLE_OBSERVER
#    ifdef CONFIG_FSM_OBSERVER
#      define FSM_ENABLE_OBSERVER 1
#    else
#      define FSM_ENABLE_OBSERVER 0
#    endif
#  endif
#  ifndef FSM_ENABLE_INTROSPECTION
#    ifdef CONFIG_FSM_INTROSPECTION
#      define FSM_ENABLE_INTROSPECTION 1
#    else
#      define FSM_ENABLE_INTROSPECTION 0
#    endif
#  endif
#endif
#ifndef FSM_ENABLE_OBSERVER
#  define FSM_ENABLE_OBSERVER 1
#endif
#ifndef FSM_ENABLE_INTROSPECTION
#  define FSM_ENABLE_INTROSPECTION 1
#endif
 
/*
 * Debug payload/event agreement checking: when a Traits declares
 * payload_matches(Event, const Payload&), the erased dispatch path verifies
 * it with FSM_PAYLOAD_ASSERT. On by default in debug builds (NDEBUG not
 * defined); predefine FSM_ENABLE_PAYLOAD_CHECKS to force either way, or
 * FSM_PAYLOAD_ASSERT to substitute your own handler for assert().
 */
#ifndef FSM_ENABLE_PAYLOAD_CHECKS
#  ifdef NDEBUG
#    define FSM_ENABLE_PAYLOAD_CHECKS 0
#  else
#    define FSM_ENABLE_PAYLOAD_CHECKS 1
#  endif
#endif
#if FSM_ENABLE_PAYLOAD_CHECKS && !defined(FSM_PAYLOAD_ASSERT)
#  include <cassert>
#  define FSM_PAYLOAD_ASSERT(cond) assert(cond)
#endif
 
/*
 * Debug range checking for dynamic deadlines: a Traits::deadline_ms() return
 * above half the Time range is clamped there in all builds (a mis-ranged
 * profile value stays *long* instead of firing instantly) and additionally
 * asserts in debug builds. Same override story as the payload checks.
 */
#ifndef FSM_ENABLE_DEADLINE_CHECKS
#  ifdef NDEBUG
#    define FSM_ENABLE_DEADLINE_CHECKS 0
#  else
#    define FSM_ENABLE_DEADLINE_CHECKS 1
#  endif
#endif
#if FSM_ENABLE_DEADLINE_CHECKS && !defined(FSM_DEADLINE_ASSERT)
#  include <cassert>
#  define FSM_DEADLINE_ASSERT(cond) assert(cond)
#endif
 
#include <array>
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <type_traits>
 
namespace fsm {
 
inline constexpr uint16_t no_row = 0xFFFF;
 
enum class status : uint8_t {
    transitioned,        
    handled_internally,  
    refused_by_row,      
    refused_guard,       
    unhandled,           
    refused_reentrant,   
    not_started,         
};
 
template <class State, class Event, class Reason>
struct result {
    fsm::status status;  
    State from;          
    State to;            
    Event event;         
    uint16_t row;        
    Reason reason;       
};
 
template <class State, class Event, class Reason>
constexpr bool accepted(const result<State, Event, Reason>& r) {
    return r.status == status::transitioned || r.status == status::handled_internally;
}
 
struct any_t {
    explicit constexpr any_t() = default;
};
inline constexpr any_t any{};
 
struct internal_t {
    explicit constexpr internal_t() = default;
};
inline constexpr internal_t internal{};
 
struct no_timeout_t {
    explicit constexpr no_timeout_t() = default;
};
inline constexpr no_timeout_t no_timeout{};
 
template <auto E>
struct event_tag {
    explicit constexpr event_tag() = default;
};
 
enum class from_kind : uint8_t { unspecified, any, state };
 
template <class State>
struct from_spec {
    from_kind k = from_kind::unspecified;
    State s{};
    constexpr from_spec() = default;
    constexpr from_spec(State st) : k(from_kind::state), s(st) {}  // NOLINT implicit
    constexpr from_spec(any_t) : k(from_kind::any) {}              // NOLINT implicit
};
 
enum class on_kind : uint8_t { unspecified, event };
 
template <class Event>
struct on_spec {
    on_kind k = on_kind::unspecified;
    Event e{};
    constexpr on_spec() = default;
    constexpr on_spec(Event ev) : k(on_kind::event), e(ev) {}  // NOLINT implicit
};
 
enum class target_kind : uint8_t { unspecified, to, internal_, refuse_ };
 
namespace detail {
template <class State>
struct to_t {
    State s;
};
template <class Reason>
struct refuse_t {
    Reason r;
};
struct empty {};
 
template <class Context, class Payload>
struct fn_sigs {
    using guard = bool (*)(Context&, const Payload&);
    using action = void (*)(Context&, const Payload&);
};
template <class Context>
struct fn_sigs<Context, void> {
    using guard = bool (*)(Context&);
    using action = void (*)(Context&);
};
}  // namespace detail
 
template <class State, class Reason>
struct target {
    target_kind k = target_kind::unspecified;
    State s{};   
    Reason r{};  
    constexpr target() = default;
    constexpr target(detail::to_t<State> t) : k(target_kind::to), s(t.s) {}    // NOLINT
    constexpr target(internal_t) : k(target_kind::internal_) {}                // NOLINT
    constexpr target(detail::refuse_t<Reason> f)                               // NOLINT
        : k(target_kind::refuse_), r(f.r) {}
};
 
template <class State>
constexpr detail::to_t<State> to(State s) {
    return {s};
}
 
template <class Reason>
constexpr detail::refuse_t<Reason> refuse(Reason r) {
    return {r};
}
 
enum class id_kind : uint8_t { unspecified, state };
 
template <class State>
struct state_id {
    id_kind k = id_kind::unspecified;
    State s{};
    constexpr state_id() = default;
    constexpr state_id(State st) : k(id_kind::state), s(st) {}  // NOLINT implicit
};
 
enum class parent_kind : uint8_t { unspecified, root, child };
 
struct root_t {
    explicit constexpr root_t() = default;
};
inline constexpr root_t root{};
 
template <class State>
struct parent_spec {
    parent_kind k = parent_kind::unspecified;
    State s{};
    constexpr parent_spec() = default;
    constexpr parent_spec(root_t) : k(parent_kind::root) {}  // NOLINT implicit
    constexpr parent_spec(parent_kind kk, State st) : k(kk), s(st) {}
};
 
template <class State>
constexpr parent_spec<State> child_of(State s) {
    return {parent_kind::child, s};
}
 
enum class initial_kind : uint8_t { leaf, start_at };
 
template <class State>
struct initial_spec {
    initial_kind k = initial_kind::leaf;
    State s{};
};
 
template <class State>
constexpr initial_spec<State> start_at(State s) {
    return {initial_kind::start_at, s};
}
 
enum class timeout_kind : uint8_t { unspecified, none, after_, after_dyn_ };
 
template <class Event>
struct timeout_spec {
    timeout_kind k = timeout_kind::unspecified;
    uint32_t ms = 0;  
    Event event{};    
    constexpr timeout_spec() = default;
    constexpr timeout_spec(no_timeout_t) : k(timeout_kind::none) {}  // NOLINT implicit
    constexpr timeout_spec(timeout_kind kk, uint32_t m, Event e) : k(kk), ms(m), event(e) {}
};
 
template <class Event>
constexpr timeout_spec<Event> after(uint32_t ms, Event e) {
    return {timeout_kind::after_, ms, e};
}
 
template <class Event>
constexpr timeout_spec<Event> after_dyn(Event e) {
    return {timeout_kind::after_dyn_, 0, e};
}
 
template <class State, class Event, class Context, class Payload = void, class Reason = uint8_t>
struct row {
    using payload_type = Payload;
    using reason_type = Reason;
    using guard_fn = typename detail::fn_sigs<Context, Payload>::guard;
    using action_fn = typename detail::fn_sigs<Context, Payload>::action;
 
    from_spec<State> from;      
    on_spec<Event> on;          
    guard_fn when = nullptr;    
    action_fn then = nullptr;   
    target<State, Reason> to;   
    const char* label = nullptr;
};
 
template <class State, class Event, class Context>
struct state_spec {
    using hook_fn = void (*)(Context&);
 
    state_id<State> state;         
    parent_spec<State> parent;     
    initial_spec<State> initial{}; 
    hook_fn entry = nullptr;       
    hook_fn exit = nullptr;        
    timeout_spec<Event> deadline;  
};
 
template <class State, class Event, class Reason>
struct observer {
    void* user = nullptr;  
    void (*on_event)(void* user, const result<State, Event, Reason>& r) = nullptr;
    void (*on_transition)(void* user, State from, State to, Event e) = nullptr;
    void (*on_timeout_fired)(void* user, State armed, Event e) = nullptr;
};
 
namespace detail {
 
template <class Time>
constexpr bool time_le(Time a, Time b) {
    using S = std::make_signed_t<Time>;
    return static_cast<S>(a - b) <= 0;
}
 
template <class Time>
constexpr bool time_lt(Time a, Time b) {
    using S = std::make_signed_t<Time>;
    return static_cast<S>(a - b) < 0;
}
 
// ---------------------------------------------------------------------------
// Constexpr table validators. All are pure loops (no recursion, cycle fuses)
// so they run both inside machine<> static_asserts and at runtime in tests.
// ---------------------------------------------------------------------------
 
template <class Spec, size_t N, class State>
constexpr size_t spec_index(const std::array<Spec, N>& specs, State s) {
    for (size_t i = 0; i < N; ++i)
        if (specs[i].state.k == id_kind::state && specs[i].state.s == s) return i;
    return N;
}
 
template <class Spec, size_t N, class State>
constexpr bool is_composite(const std::array<Spec, N>& specs, State s) {
    for (size_t i = 0; i < N; ++i)
        if (specs[i].parent.k == parent_kind::child && specs[i].parent.s == s) return true;
    return false;
}
 
template <class Spec, size_t N, class State>
constexpr bool is_ancestor(const std::array<Spec, N>& specs, State a, State x) {
    State cur = x;
    for (size_t fuse = 0; fuse <= N; ++fuse) {
        const size_t i = spec_index(specs, cur);
        if (i == N || specs[i].parent.k != parent_kind::child) return false;
        cur = specs[i].parent.s;
        if (cur == a) return true;
    }
    return false;
}
 
template <class Spec, size_t N, class State>
constexpr size_t depth_of(const std::array<Spec, N>& specs, State s) {
    size_t d = 0;
    State cur = s;
    for (size_t fuse = 0; fuse <= N; ++fuse) {
        const size_t i = spec_index(specs, cur);
        if (i == N || specs[i].parent.k != parent_kind::child) return d;
        cur = specs[i].parent.s;
        ++d;
    }
    return d;
}
 
template <class Spec, size_t N>
constexpr size_t max_depth(const std::array<Spec, N>& specs) {
    size_t m = 0;
    for (size_t i = 0; i < N; ++i) {
        if (specs[i].state.k != id_kind::state) continue;
        const size_t d = depth_of(specs, specs[i].state.s);
        if (d > m) m = d;
    }
    return m;
}
 
template <class Spec, size_t N, class State>
constexpr State leaf_of(const std::array<Spec, N>& specs, State s) {
    State cur = s;
    for (size_t fuse = 0; fuse <= N; ++fuse) {
        const size_t i = spec_index(specs, cur);
        if (i == N || specs[i].initial.k != initial_kind::start_at) return cur;
        cur = specs[i].initial.s;
    }
    return cur;
}
 
template <size_t StateCount, class Spec, size_t N>
constexpr bool states_complete(const std::array<Spec, N>& specs) {
    for (size_t i = 0; i < N; ++i)
        if (specs[i].state.k != id_kind::state) return false;
    if (N != StateCount) return false;
    for (size_t v = 0; v < StateCount; ++v) {
        bool found = false;
        for (size_t i = 0; i < N; ++i)
            if (static_cast<size_t>(specs[i].state.s) == v) found = true;
        if (!found) return false;
    }
    return true;
}
 
template <class Spec, size_t N>
constexpr bool no_duplicate_specs(const std::array<Spec, N>& specs) {
    for (size_t i = 0; i < N; ++i)
        for (size_t j = i + 1; j < N; ++j)
            if (specs[i].state.k == id_kind::state && specs[j].state.k == id_kind::state &&
                specs[i].state.s == specs[j].state.s)
                return false;
    return true;
}
 
template <class Spec, size_t N>
constexpr bool parents_valid(const std::array<Spec, N>& specs) {
    for (size_t i = 0; i < N; ++i) {
        if (specs[i].parent.k != parent_kind::child) continue;
        if (spec_index(specs, specs[i].parent.s) == N) return false;
        // Walk up; a chain longer than N states is a cycle.
        auto cur = specs[i].state.s;
        size_t steps = 0;
        for (; steps <= N; ++steps) {
            const size_t p = spec_index(specs, cur);
            if (p == N || specs[p].parent.k != parent_kind::child) break;
            cur = specs[p].parent.s;
        }
        if (steps > N) return false;
    }
    return true;
}
 
template <class Spec, size_t N>
constexpr bool composites_declare_initial(const std::array<Spec, N>& specs) {
    for (size_t i = 0; i < N; ++i) {
        if (specs[i].state.k != id_kind::state) continue;
        if (is_composite(specs, specs[i].state.s) &&
            specs[i].initial.k != initial_kind::start_at)
            return false;
    }
    return true;
}
 
template <class Spec, size_t N>
constexpr bool leaves_have_no_initial(const std::array<Spec, N>& specs) {
    for (size_t i = 0; i < N; ++i) {
        if (specs[i].state.k != id_kind::state) continue;
        if (!is_composite(specs, specs[i].state.s) &&
            specs[i].initial.k == initial_kind::start_at)
            return false;
    }
    return true;
}
 
template <class Spec, size_t N>
constexpr bool initials_belong(const std::array<Spec, N>& specs) {
    for (size_t i = 0; i < N; ++i) {
        if (specs[i].state.k != id_kind::state) continue;
        if (specs[i].initial.k != initial_kind::start_at) continue;
        const auto s = specs[i].state.s;
        const size_t c = spec_index(specs, specs[i].initial.s);
        if (c == N) return false;
        if (specs[c].parent.k != parent_kind::child || specs[c].parent.s != s) return false;
        // Descent must reach a non-start_at spec within N steps.
        auto cur = s;
        bool leaf_reached = false;
        for (size_t fuse = 0; fuse <= N; ++fuse) {
            const size_t k = spec_index(specs, cur);
            if (k == N) return false;
            if (specs[k].initial.k != initial_kind::start_at) {
                leaf_reached = true;
                break;
            }
            cur = specs[k].initial.s;
        }
        if (!leaf_reached) return false;
    }
    return true;
}
 
template <class Row, size_t M>
constexpr bool rows_have_targets(const std::array<Row, M>& rows) {
    for (size_t i = 0; i < M; ++i)
        if (rows[i].to.k == target_kind::unspecified || rows[i].from.k == from_kind::unspecified ||
            rows[i].on.k == on_kind::unspecified)
            return false;
    return true;
}
 
template <size_t StateCount, size_t EventCount, class Row, size_t M, class Spec, size_t N>
constexpr bool rows_reference_valid(const std::array<Row, M>& rows,
                                    const std::array<Spec, N>& specs) {
    for (size_t i = 0; i < M; ++i) {
        if (rows[i].from.k == from_kind::state && spec_index(specs, rows[i].from.s) == N)
            return false;
        if (rows[i].on.k != on_kind::event || static_cast<size_t>(rows[i].on.e) >= EventCount)
            return false;
        if (rows[i].to.k == target_kind::to && spec_index(specs, rows[i].to.s) == N) return false;
    }
    return true;
}
 
template <class Row>
constexpr bool same_slot(const Row& a, const Row& b) {
    if (a.from.k != b.from.k) return false;
    if (a.from.k == from_kind::state && a.from.s != b.from.s) return false;
    return a.on.k == on_kind::event && b.on.k == on_kind::event && a.on.e == b.on.e;
}
 
template <class Row, size_t M>
constexpr bool rows_no_duplicate_unguarded(const std::array<Row, M>& rows) {
    for (size_t i = 0; i < M; ++i)
        for (size_t j = i + 1; j < M; ++j)
            if (same_slot(rows[i], rows[j]) && rows[i].when == nullptr && rows[j].when == nullptr)
                return false;
    return true;
}
 
template <class Row, size_t M>
constexpr bool rows_no_unreachable(const std::array<Row, M>& rows) {
    for (size_t i = 0; i < M; ++i)
        for (size_t j = i + 1; j < M; ++j)
            if (same_slot(rows[i], rows[j]) && rows[i].when == nullptr && rows[j].when != nullptr)
                return false;
    return true;
}
 
template <class Row, size_t M>
constexpr bool rows_refuse_have_no_action(const std::array<Row, M>& rows) {
    for (size_t i = 0; i < M; ++i)
        if (rows[i].to.k == target_kind::refuse_ && rows[i].then != nullptr) return false;
    return true;
}
 
template <class Spec, size_t N>
constexpr bool parents_declared(const std::array<Spec, N>& specs) {
    for (size_t i = 0; i < N; ++i)
        if (specs[i].parent.k == parent_kind::unspecified) return false;
    return true;
}
 
template <class Spec, size_t N>
constexpr bool any_dynamic_deadline(const std::array<Spec, N>& specs) {
    for (size_t i = 0; i < N; ++i)
        if (specs[i].deadline.k == timeout_kind::after_dyn_) return true;
    return false;
}
 
template <class Spec, size_t N>
constexpr bool deadlines_declared(const std::array<Spec, N>& specs) {
    for (size_t i = 0; i < N; ++i)
        if (specs[i].deadline.k == timeout_kind::unspecified) return false;
    return true;
}
 
template <class Time, class Spec, size_t N>
constexpr bool deadlines_fit(const std::array<Spec, N>& specs) {
    constexpr uint64_t half = static_cast<uint64_t>(static_cast<Time>(-1)) / 2;
    for (size_t i = 0; i < N; ++i)
        if (specs[i].deadline.k == timeout_kind::after_ &&
            static_cast<uint64_t>(specs[i].deadline.ms) > half)
            return false;
    return true;
}
 
template <class Spec, size_t N, class Row, size_t M>
constexpr bool timeouts_consumable(const std::array<Spec, N>& specs,
                                   const std::array<Row, M>& rows) {
    for (size_t i = 0; i < N; ++i) {
        if (specs[i].deadline.k != timeout_kind::after_ &&
            specs[i].deadline.k != timeout_kind::after_dyn_)
            continue;
        const auto s = specs[i].state.s;
        const auto ev = specs[i].deadline.event;
        bool ok = false;
        for (size_t r = 0; r < M && !ok; ++r) {
            if (rows[r].on.k != on_kind::event || rows[r].on.e != ev) continue;
            if (rows[r].from.k == from_kind::any) ok = true;
            else if (rows[r].from.k == from_kind::state &&
                     (rows[r].from.s == s || is_ancestor(specs, rows[r].from.s, s)))
                ok = true;
        }
        if (!ok) return false;
    }
    return true;
}
 
template <class Row, class State, class Event>
constexpr bool row_matches_state(const Row& r, State lvl, Event e) {
    return r.from.k == from_kind::state && r.from.s == lvl &&
           r.on.k == on_kind::event && r.on.e == e;
}
 
template <class Row, class Event>
constexpr bool row_matches_any(const Row& r, Event e) {
    return r.from.k == from_kind::any && r.on.k == on_kind::event && r.on.e == e;
}
 
template <class Spec, size_t N, class Row, size_t M, class State, class Event>
constexpr bool matches(const std::array<Row, M>& rows, const std::array<Spec, N>& specs,
                       State leaf, Event e) {
    State lvl = leaf;
    for (size_t fuse = 0; fuse <= N; ++fuse) {
        for (size_t r = 0; r < M; ++r)
            if (row_matches_state(rows[r], lvl, e)) return true;
        const size_t i = spec_index(specs, lvl);
        if (i == N || specs[i].parent.k != parent_kind::child) break;
        lvl = specs[i].parent.s;
    }
    for (size_t r = 0; r < M; ++r)
        if (row_matches_any(rows[r], e)) return true;
    return false;
}
 
template <size_t EventCount, class Spec, size_t N, class Row, size_t M>
constexpr bool exhaustive(const std::array<Spec, N>& specs, const std::array<Row, M>& rows) {
    for (size_t i = 0; i < N; ++i) {
        if (specs[i].state.k != id_kind::state) continue;
        const auto s = specs[i].state.s;
        if (is_composite(specs, s)) continue;  // machines rest only at leaves
        for (size_t e = 0; e < EventCount; ++e)
            if (!matches(rows, specs, s, static_cast<decltype(specs[i].deadline.event)>(e)))
                return false;
    }
    return true;
}
 
#if FSM_ENABLE_INTROSPECTION
struct line_buf {
    char b[224] = {};
    size_t n = 0;
    constexpr void put(char c) {
        if (n + 1 < sizeof b) b[n++] = c;
        b[n] = '\0';
    }
    constexpr void str(const char* s) {
        while (*s != '\0') put(*s++);
    }
    constexpr void u64(uint64_t v) {
        char tmp[20];
        size_t i = 0;
        do {
            tmp[i++] = static_cast<char>('0' + v % 10);
            v /= 10;
        } while (v != 0);
        while (i > 0) put(tmp[--i]);
    }
    constexpr void reset() {
        n = 0;
        b[0] = '\0';
    }
};
#endif  // FSM_ENABLE_INTROSPECTION
 
// Optional-trait detection (evaluated on the *complete* Traits type at
// machine instantiation, never inside the user's struct definition).
template <class T>
concept has_time_trait = requires { typename T::Time; };
template <class T>
concept has_strict_trait = requires {
    { T::strict } -> std::convertible_to<bool>;
};
template <class T, class State>
concept has_state_names = requires(State s) {
    { T::state_name(s) } -> std::convertible_to<const char*>;
};
template <class T, class Event>
concept has_event_names = requires(Event e) {
    { T::event_name(e) } -> std::convertible_to<const char*>;
};
template <class T, class Reason>
concept has_reason_names = requires(Reason r) {
    { T::reason_name(r) } -> std::convertible_to<const char*>;
};
template <class T, class Event, class Payload>
concept has_payload_matches = requires(Event e, const Payload& p) {
    { T::payload_matches(e, p) } -> std::convertible_to<bool>;
};
template <class T, class State, class Context>
concept has_deadline_ms = requires(State s, const Context& c) {
    { T::deadline_ms(s, c) } -> std::convertible_to<uint32_t>;
};
template <class T>
concept has_post_depth = requires {
    { T::post_queue_depth } -> std::convertible_to<size_t>;
};
 
template <class T>
constexpr size_t post_depth_of() {
    if constexpr (has_post_depth<T>) return T::post_queue_depth;
    else return 4;
}
 
template <class T>
struct time_of {
    using type = uint32_t;
};
template <has_time_trait T>
struct time_of<T> {
    using type = typename T::Time;
};
 
template <class T>
constexpr bool strict_of() {
    if constexpr (has_strict_trait<T>) return T::strict;
    else return true;
}
 
}  // namespace detail
 
template <class Traits>
class machine {
public:
    using state_type = typename Traits::State;
    using event_type = typename Traits::Event;
    using context_type = typename Traits::Context;
    using rows_array = std::remove_cvref_t<decltype(Traits::rows)>;
    using specs_array = std::remove_cvref_t<decltype(Traits::states)>;
    using row_type = typename rows_array::value_type;
    using spec_type = typename specs_array::value_type;
    using payload_type = typename row_type::payload_type;  
    using reason_type = typename row_type::reason_type;
    using time_type = typename detail::time_of<Traits>::type;
    using result_type = result<state_type, event_type, reason_type>;
    using observer_type = observer<state_type, event_type, reason_type>;
 
    static constexpr size_t state_count = static_cast<size_t>(state_type::Count);
    static constexpr size_t event_count = static_cast<size_t>(event_type::Count);
    static constexpr size_t row_count = Traits::rows.size();
    static constexpr bool strict = detail::strict_of<Traits>();
 
private:
    // ---- compile-time validation (messages pinned by the compile-fail suite)
    static_assert(state_count <= 256, "fsm: at most 256 states (spec index is uint8_t)");
    static_assert(row_count < static_cast<size_t>(no_row),
                  "fsm: row count must stay below fsm::no_row (0xFFFF)");
    // Ordered so each table defect trips its own message first: clang stops
    // at the first failing assert, and a duplicated spec necessarily also
    // fails states_complete (some enum value must then be missing).
    static_assert(detail::no_duplicate_specs(Traits::states), "fsm: duplicate state_spec");
    static_assert(detail::states_complete<state_count>(Traits::states),
                  "fsm: every state needs exactly one state_spec");
    static_assert(detail::parents_declared(Traits::states),
                  "fsm: state_spec .parent is mandatory (fsm::root/fsm::child_of)");
    static_assert(detail::parents_valid(Traits::states), "fsm: parent graph must be acyclic");
    static_assert(detail::composites_declare_initial(Traits::states),
                  "fsm: composite state must declare start_at initial");
    static_assert(detail::leaves_have_no_initial(Traits::states),
                  "fsm: leaf state must not declare initial");
    static_assert(detail::initials_belong(Traits::states),
                  "fsm: initial child's parent must be its composite");
    static_assert(detail::rows_have_targets(Traits::rows),
                  "fsm: row .to is mandatory (fsm::to/internal/refuse)");
    static_assert(detail::rows_reference_valid<state_count, event_count>(Traits::rows,
                                                                         Traits::states),
                  "fsm: row references invalid state or event");
    static_assert(detail::rows_no_duplicate_unguarded(Traits::rows),
                  "fsm: ambiguous rows: duplicate unguarded (from, event)");
    static_assert(detail::rows_no_unreachable(Traits::rows),
                  "fsm: unreachable row after unguarded row for same (from, event)");
    static_assert(detail::rows_refuse_have_no_action(Traits::rows),
                  "fsm: refuse row must not declare an action (never runs on refusal)");
    static_assert(detail::deadlines_declared(Traits::states),
                  "fsm: state_spec .deadline is mandatory (fsm::after/no_timeout)");
    static_assert(detail::deadlines_fit<time_type>(Traits::states),
                  "fsm: deadline duration exceeds half the Time range");
    static_assert(detail::timeouts_consumable(Traits::states, Traits::rows),
                  "fsm: timeout event not consumable from its state");
    static_assert(!detail::any_dynamic_deadline(Traits::states) ||
                      detail::has_deadline_ms<Traits, state_type, context_type>,
                  "fsm: after_dyn states require Traits::deadline_ms(State, const Context&)");
    static_assert(!strict || detail::exhaustive<event_count>(Traits::states, Traits::rows),
                  "fsm: unhandled (state, event) pair in strict machine");
    static_assert(detail::spec_index(Traits::states, Traits::initial) < state_count,
                  "fsm: machine initial state has no state_spec");
    static_assert(std::is_unsigned_v<time_type>, "fsm: Time must be an unsigned integer type");
    static_assert(std::is_void_v<payload_type> ||
                      (std::is_default_constructible_v<payload_type> &&
                       std::is_trivially_copyable_v<payload_type>),
                  "fsm: Payload must be default-constructible and trivially copyable");
 
    using payload_arg = std::conditional_t<std::is_void_v<payload_type>, detail::empty,
                                           std::remove_cv_t<payload_type>>;
 
    static constexpr size_t max_depth_v = detail::max_depth(Traits::states);
 
    static constexpr std::array<uint8_t, state_count> spec_pos_ = [] {
        std::array<uint8_t, state_count> a{};
        for (size_t v = 0; v < state_count; ++v)
            a[v] = static_cast<uint8_t>(
                detail::spec_index(Traits::states, static_cast<state_type>(v)));
        return a;
    }();
 
    static constexpr const spec_type& spec_of(state_type s) {
        return Traits::states[spec_pos_[static_cast<size_t>(s)]];
    }
 
    static constexpr std::array<uint8_t, state_count> depth_ = [] {
        std::array<uint8_t, state_count> a{};
        for (size_t v = 0; v < state_count; ++v)
            a[v] = static_cast<uint8_t>(
                detail::depth_of(Traits::states, static_cast<state_type>(v)));
        return a;
    }();
 
    struct slot {
        time_type at;
        bool armed;
    };
 
    static constexpr size_t post_depth = detail::post_depth_of<Traits>();
    static_assert(post_depth >= 1 && post_depth <= 255,
                  "fsm: post_queue_depth must be in [1, 255]");
 
    struct pending {
        event_type e;
        payload_arg p;
    };
 
    context_type* ctx_;
    state_type leaf_{};
    bool started_ = false;
    bool in_dispatch_ = false;
#if FSM_ENABLE_OBSERVER
    bool in_notify_ = false;
#endif
    slot slots_[state_count] = {};
    pending posts_[post_depth] = {};
    uint8_t post_head_ = 0;
    uint8_t post_count_ = 0;
#if FSM_ENABLE_OBSERVER
    const observer_type* obs_ = nullptr;
#endif
 
public:
    explicit constexpr machine(context_type& ctx) : ctx_(&ctx) {}
 
    machine(const machine&) = delete;
    machine& operator=(const machine&) = delete;
 
    void start(time_type now) {
        if (started_ || in_dispatch_) return;
        started_ = true;
        in_dispatch_ = true;
        enter_chain_to(Traits::initial, now);
        descend_initials(now);
        in_dispatch_ = false;
        drain_posts(now);  // entry hooks may have post()ed follow-up events
    }
 
    bool post(event_type e) { return post_impl(e, payload_arg{}); }
 
    size_t posts_pending() const { return post_count_; }
 
    template <event_type E, class Arg>
        requires(!std::is_void_v<payload_type> && requires(const Arg& a) {
            { Traits::make_payload(event_tag<E>{}, a) } -> std::convertible_to<payload_arg>;
        })
    bool post(const Arg& arg) {
        return post_impl(E, Traits::make_payload(event_tag<E>{}, arg));
    }
 
    template <event_type E>
        requires(!std::is_void_v<payload_type> && requires {
            { Traits::make_payload(event_tag<E>{}) } -> std::convertible_to<payload_arg>;
        })
    bool post() {
        return post_impl(E, Traits::make_payload(event_tag<E>{}));
    }
 
    template <class P = payload_type>
        requires(!std::is_void_v<P> && std::is_same_v<P, payload_type>)
    bool post(event_type e, const P& p) {
        return post_impl(e, p);
    }
 
    result_type dispatch(event_type e, time_type now) {
        const result_type r = do_dispatch(e, payload_arg{}, now);
        if (!in_dispatch_) drain_posts(now);
        return r;
    }
 
    template <class P = payload_type>
        requires(!std::is_void_v<P> && std::is_same_v<P, payload_type>)
    result_type dispatch(event_type e, const P& p, time_type now) {
        const result_type r = do_dispatch(e, p, now);
        if (!in_dispatch_) drain_posts(now);
        return r;
    }
 
    template <event_type E, class Arg>
        requires(!std::is_void_v<payload_type> && requires(const Arg& a) {
            { Traits::make_payload(event_tag<E>{}, a) } -> std::convertible_to<payload_arg>;
        })
    result_type dispatch(const Arg& arg, time_type now) {
        return dispatch(E, Traits::make_payload(event_tag<E>{}, arg), now);
    }
 
    template <event_type E>
        requires(!std::is_void_v<payload_type> && requires {
            { Traits::make_payload(event_tag<E>{}) } -> std::convertible_to<payload_arg>;
        })
    result_type dispatch(time_type now) {
        return dispatch(E, Traits::make_payload(event_tag<E>{}), now);
    }
 
    bool next_deadline(time_type& out) const {
        bool found = false;
        for (size_t i = 0; i < state_count; ++i) {
            if (!slots_[i].armed) continue;
            if (!found || detail::time_lt<time_type>(slots_[i].at, out)) {
                out = slots_[i].at;
                found = true;
            }
        }
        return found;
    }
 
    unsigned service(time_type now) {
        if (in_dispatch_) return 0;
        unsigned fired = 0;
        for (size_t fuse = 0; fuse < 4 * state_count; ++fuse) {
            size_t best = state_count;
            for (size_t i = 0; i < state_count; ++i) {
                if (!slots_[i].armed || !detail::time_le<time_type>(slots_[i].at, now)) continue;
                if (best == state_count ||
                    detail::time_lt<time_type>(slots_[i].at, slots_[best].at))
                    best = i;
            }
            if (best == state_count) break;
            slots_[best].armed = false;
            const state_type owner = static_cast<state_type>(best);
            const event_type ev = spec_of(owner).deadline.event;
#if FSM_ENABLE_OBSERVER
            if (obs_ != nullptr && obs_->on_timeout_fired != nullptr)
                obs_->on_timeout_fired(obs_->user, owner, ev);
#endif
            do_dispatch(ev, payload_arg{}, now);
            drain_posts(now);  // a fired timeout's actions may have post()ed
            ++fired;
        }
        return fired;
    }
 
    state_type state() const { return leaf_; }
 
    bool in(state_type s) const {
        if (!started_) return false;
        state_type cur = leaf_;
        for (size_t fuse = 0; fuse <= state_count; ++fuse) {
            if (cur == s) return true;
            const auto& p = spec_of(cur).parent;
            if (p.k != parent_kind::child) return false;
            cur = p.s;
        }
        return false;
    }
 
    bool started() const { return started_; }
 
#if FSM_ENABLE_OBSERVER
    void set_observer(const observer_type* o) { obs_ = o; }
#endif
 
#if FSM_ENABLE_INTROSPECTION
    template <class W>
    void dump(W&& write) const {
        detail::line_buf lb;
        lb.str("fsm: ");
        lb.u64(state_count);
        lb.str(" states, ");
        lb.u64(row_count);
        lb.str(" rows, leaf=");
        put_state_name(lb, leaf_);
        lb.str(", started=");
        lb.u64(started_ ? 1 : 0);
        write(static_cast<const char*>(lb.b));
        for (size_t i = 0; i < row_count; ++i) {
            const auto& r = Traits::rows[i];
            lb.reset();
            lb.str("row ");
            lb.u64(i);
            lb.str(": ");
            if (r.from.k == from_kind::any) lb.str("any");
            else put_state_name(lb, r.from.s);
            lb.str(" --");
            put_event_name(lb, r.on.e);
            if (r.when != nullptr) lb.str("[guard]");
            if (r.then != nullptr) lb.str("/action");
            lb.str("--> ");
            switch (r.to.k) {
                case target_kind::to: put_state_name(lb, r.to.s); break;
                case target_kind::internal_: lb.str("internal"); break;
                case target_kind::refuse_:
                    lb.str("refuse(");
                    put_reason_name(lb, r.to.r);
                    lb.str(")");
                    break;
                default: lb.str("?"); break;
            }
            if (r.label != nullptr) {
                lb.str("  # ");
                lb.str(r.label);
            }
            write(static_cast<const char*>(lb.b));
        }
        for (size_t i = 0; i < state_count; ++i) {
            if (!slots_[i].armed) continue;
            lb.reset();
            lb.str("armed: ");
            put_state_name(lb, static_cast<state_type>(i));
            lb.str(" at ");
            lb.u64(static_cast<uint64_t>(slots_[i].at));
            write(static_cast<const char*>(lb.b));
        }
    }
 
    template <class F>
    static constexpr void for_each_row(F&& f) {
        for (size_t i = 0; i < row_count; ++i) f(Traits::rows[i], i);
    }
 
    template <class F>
    static constexpr void for_each_state(F&& f) {
        for (size_t i = 0; i < state_count; ++i) f(Traits::states[i], i);
    }
 
    static constexpr void put_reason_name(detail::line_buf& lb, reason_type r) {
        if constexpr (detail::has_reason_names<Traits, reason_type>) {
            lb.str(Traits::reason_name(r));
        } else {
            lb.u64(static_cast<uint64_t>(r));
        }
    }
 
    static constexpr void put_state_name(detail::line_buf& lb, state_type s) {
        if constexpr (detail::has_state_names<Traits, state_type>) {
            lb.str(Traits::state_name(s));
        } else {
            lb.put('s');
            lb.u64(static_cast<uint64_t>(s));
        }
    }
 
    static constexpr void put_event_name(detail::line_buf& lb, event_type e) {
        if constexpr (detail::has_event_names<Traits, event_type>) {
            lb.str(Traits::event_name(e));
        } else {
            lb.put('e');
            lb.u64(static_cast<uint64_t>(e));
        }
    }
#endif  // FSM_ENABLE_INTROSPECTION
 
private:
    result_type make(fsm::status st, state_type from, state_type to, event_type e, uint16_t row_i,
                     reason_type reason) const {
        return result_type{st, from, to, e, row_i, reason};
    }
 
    result_type notify(const result_type& r) {
#if FSM_ENABLE_OBSERVER
        if (in_notify_) return r;
        in_notify_ = true;
        if (obs_ != nullptr && obs_->on_event != nullptr) obs_->on_event(obs_->user, r);
        if (obs_ != nullptr && obs_->on_transition != nullptr &&
            r.status == fsm::status::transitioned)
            obs_->on_transition(obs_->user, r.from, r.to, r.event);
        in_notify_ = false;
#endif
        return r;
    }
 
    bool post_impl(event_type e, const payload_arg& p) {
        if (!started_ || post_count_ >= post_depth) return false;
        posts_[(post_head_ + post_count_) % post_depth] = pending{e, p};
        ++post_count_;
        return true;
    }
 
    void drain_posts(time_type now) {
        for (size_t fuse = 0; fuse < 4 * post_depth && post_count_ > 0; ++fuse) {
            const pending pn = posts_[post_head_];
            post_head_ = static_cast<uint8_t>((post_head_ + 1) % post_depth);
            --post_count_;
            do_dispatch(pn.e, pn.p, now);
        }
    }
 
    bool call_guard(typename row_type::guard_fn g, const payload_arg& p) {
        if constexpr (std::is_void_v<payload_type>) {
            (void)p;
            return g(*ctx_);
        } else {
            return g(*ctx_, p);
        }
    }
 
    void call_action(typename row_type::action_fn a, const payload_arg& p) {
        if (a == nullptr) return;
        if constexpr (std::is_void_v<payload_type>) {
            (void)p;
            a(*ctx_);
        } else {
            a(*ctx_, p);
        }
    }
 
    void do_enter(state_type s, time_type now) {
        const auto& sp = spec_of(s);
        if (sp.entry != nullptr) sp.entry(*ctx_);
        if (sp.deadline.k == timeout_kind::after_) {
            slots_[static_cast<size_t>(s)] = {static_cast<time_type>(now + sp.deadline.ms), true};
        } else if constexpr (detail::has_deadline_ms<Traits, state_type, context_type>) {
            if (sp.deadline.k == timeout_kind::after_dyn_) {
                // Runtime-valued deadline, re-consulted on every entry
                // (self-transition re-entry included). 0 means "due now".
                constexpr uint64_t half = static_cast<uint64_t>(static_cast<time_type>(-1)) / 2;
                uint64_t ms = Traits::deadline_ms(s, *ctx_);
#if FSM_ENABLE_DEADLINE_CHECKS
                FSM_DEADLINE_ASSERT(ms <= half);
#endif
                if (ms > half) ms = half;  // stay long rather than fire instantly
                slots_[static_cast<size_t>(s)] = {
                    static_cast<time_type>(now + static_cast<time_type>(ms)), true};
            }
        }
    }
 
    void do_exit(state_type s) {
        slots_[static_cast<size_t>(s)].armed = false;
        const auto& sp = spec_of(s);
        if (sp.exit != nullptr) sp.exit(*ctx_);
    }
 
    void enter_path(state_type target, state_type above, bool have_above, time_type now) {
        state_type path[max_depth_v + 1];
        size_t n = 0;
        state_type cur = target;
        while (true) {
            if (have_above && cur == above) break;
            path[n++] = cur;
            const auto& p = spec_of(cur).parent;
            if (p.k != parent_kind::child) break;
            cur = p.s;
        }
        while (n > 0) do_enter(path[--n], now);
        leaf_ = target;
    }
 
    void enter_chain_to(state_type target, time_type now) {
        enter_path(target, target, false, now);
    }
 
    void descend_initials(time_type now) {
        state_type cur = leaf_;
        for (size_t fuse = 0; fuse <= state_count; ++fuse) {
            const auto& ini = spec_of(cur).initial;
            if (ini.k != initial_kind::start_at) break;
            cur = ini.s;
            do_enter(cur, now);
        }
        leaf_ = cur;
    }
 
    void exit_up(state_type stop, bool inclusive) {
        state_type cur = leaf_;
        for (size_t fuse = 0; fuse <= state_count; ++fuse) {
            if (!inclusive && cur == stop) return;
            do_exit(cur);
            if (inclusive && cur == stop) return;
            const auto& p = spec_of(cur).parent;
            if (p.k != parent_kind::child) return;
            cur = p.s;
        }
    }
 
    void exit_all() {
        state_type cur = leaf_;
        for (size_t fuse = 0; fuse <= state_count; ++fuse) {
            do_exit(cur);
            const auto& p = spec_of(cur).parent;
            if (p.k != parent_kind::child) return;
            cur = p.s;
        }
    }
 
    static state_type lca_of(state_type a, state_type b, bool& found) {
        size_t da = depth_[static_cast<size_t>(a)];
        size_t db = depth_[static_cast<size_t>(b)];
        while (da > db) {
            a = spec_of(a).parent.s;
            --da;
        }
        while (db > da) {
            b = spec_of(b).parent.s;
            --db;
        }
        for (size_t fuse = 0; fuse <= state_count; ++fuse) {
            if (a == b) {
                found = true;
                return a;
            }
            const auto& pa = spec_of(a).parent;
            const auto& pb = spec_of(b).parent;
            if (pa.k != parent_kind::child || pb.k != parent_kind::child) break;
            a = pa.s;
            b = pb.s;
        }
        found = false;
        return a;
    }
 
    result_type execute(const row_type& r, uint16_t idx, state_type matched_lvl, event_type e,
                        const payload_arg& p, time_type now) {
        const state_type before = leaf_;
        switch (r.to.k) {
            case target_kind::refuse_:
                return make(fsm::status::refused_by_row, before, before, e, idx, r.to.r);
            case target_kind::internal_:
                call_action(r.then, p);
                return make(fsm::status::handled_internally, before, before, e, idx,
                            reason_type{});
            case target_kind::to:
            default:
                break;
        }
        const state_type main_src =
            (r.from.k == from_kind::any) ? before : matched_lvl;
        const state_type tgt = r.to.s;
        if (tgt == main_src) {
            // Self-transition: external semantics — full exit and re-entry.
            exit_up(main_src, true);
            call_action(r.then, p);
            const auto& ps = spec_of(main_src).parent;
            enter_path(tgt, ps.s, ps.k == parent_kind::child, now);
        } else {
            bool have_lca = false;
            const state_type lca = lca_of(main_src, tgt, have_lca);
            if (have_lca) {
                exit_up(lca, false);
                call_action(r.then, p);
                enter_path(tgt, lca, true, now);
            } else {
                exit_all();
                call_action(r.then, p);
                enter_path(tgt, tgt, false, now);
            }
        }
        descend_initials(now);
        return make(fsm::status::transitioned, before, leaf_, e, idx, reason_type{});
    }
 
    result_type do_dispatch(event_type e, const payload_arg& p, time_type now) {
#if FSM_ENABLE_PAYLOAD_CHECKS
        // Erased-path guardrail: with a payload_matches() hook declared, a
        // payload whose content disagrees with the event trips the assert in
        // debug builds (queues, facades and post() all funnel through here).
        if constexpr (!std::is_void_v<payload_type> &&
                      detail::has_payload_matches<Traits, event_type, payload_arg>) {
            FSM_PAYLOAD_ASSERT(Traits::payload_matches(e, p));
        }
#endif
        if (in_dispatch_)
            return notify(make(fsm::status::refused_reentrant, leaf_, leaf_, e, no_row,
                               reason_type{}));
        if (!started_)
            return notify(
                make(fsm::status::not_started, leaf_, leaf_, e, no_row, reason_type{}));
        in_dispatch_ = true;
        uint16_t first_match = no_row;
        state_type lvl = leaf_;
        for (size_t fuse = 0; fuse <= state_count; ++fuse) {
            for (uint16_t i = 0; i < row_count; ++i) {
                const auto& r = Traits::rows[i];
                if (!detail::row_matches_state(r, lvl, e)) continue;
                if (first_match == no_row) first_match = i;
                if (r.when != nullptr && !call_guard(r.when, p)) continue;
                const result_type res = notify(execute(r, i, lvl, e, p, now));
                in_dispatch_ = false;
                return res;
            }
            const auto& par = spec_of(lvl).parent;
            if (par.k != parent_kind::child) break;
            lvl = par.s;
        }
        for (uint16_t i = 0; i < row_count; ++i) {
            const auto& r = Traits::rows[i];
            if (!detail::row_matches_any(r, e)) continue;
            if (first_match == no_row) first_match = i;
            if (r.when != nullptr && !call_guard(r.when, p)) continue;
            const result_type res = notify(execute(r, i, leaf_, e, p, now));
            in_dispatch_ = false;
            return res;
        }
        const result_type res = notify(make(first_match == no_row
                                                ? fsm::status::unhandled
                                                : fsm::status::refused_guard,
                                            leaf_, leaf_, e, first_match, reason_type{}));
        in_dispatch_ = false;
        return res;
    }
};
 
}  // namespace fsm
 
#endif // FSM_FSM_HPP