ready_active_safe/

model.rs

//! Core types for the lifecycle engine.
//!
//! These types are always available and `no_std`-compatible (using `alloc`
//! for heap allocation). They define the fundamental contracts that every
//! lifecycle implementation must satisfy.

use alloc::vec::Vec;
use core::fmt;

use crate::error::LifecycleError;

/// A requested change from one mode to another.
///
/// Produced inside a [`Decision`] when an event triggers a mode transition.
/// The runtime inspects this value to determine whether the system should
/// move to a new mode.
///
/// # Examples
///
/// ```
/// use ready_active_safe::Decision;
///
/// let d: Decision<&str, (), ()> = Decision::transition("active");
/// let change = d.mode_change();
/// assert_eq!(change.map(|mc| mc.target), Some("active"));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct ModeChange<M> {
    /// The mode to transition to.
    pub target: M,
}

/// The outcome of processing an event through [`Machine::on_event`].
///
/// A `Decision` captures two orthogonal concerns:
/// - Whether the system should change mode ([`ModeChange`]).
/// - What commands the runtime should execute.
///
/// Decisions are **pure data**. They describe intent, not side effects.
/// The runtime is responsible for interpreting and executing them.
///
/// # Examples
///
/// ```
/// use ready_active_safe::Decision;
///
/// #[derive(Debug, Clone, PartialEq, Eq)]
/// enum Mode { Ready, Active }
///
/// // Stay in the current mode with no commands
/// let stay: Decision<Mode, &str, ()> = Decision::stay();
/// assert!(stay.target_mode().is_none());
///
/// // Transition to a new mode
/// let go: Decision<Mode, &str, ()> = Decision::transition(Mode::Active);
/// assert_eq!(go.target_mode(), Some(&Mode::Active));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct Decision<M, C, E = core::convert::Infallible> {
    /// An optional mode change. `None` means stay in the current mode.
    change: Option<ModeChange<M>>,
    /// Commands for the runtime to execute.
    commands: Vec<C>,
    /// Marker for the error type. Used by the trait contract but not
    /// stored in the decision itself.
    _error: core::marker::PhantomData<E>,
}

impl<M, C, E> Decision<M, C, E> {
    /// Creates a decision that stays in the current mode with no commands.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// let d: Decision<(), (), ()> = Decision::stay();
    /// assert!(d.mode_change().is_none());
    /// assert!(d.commands().is_empty());
    /// ```
    #[must_use]
    pub const fn stay() -> Self {
        Self {
            change: None,
            commands: Vec::new(),
            _error: core::marker::PhantomData,
        }
    }

    /// Creates a decision that transitions to the given mode.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// let d: Decision<&str, (), ()> = Decision::transition("active");
    /// assert_eq!(d.mode_change().map(|mc| mc.target), Some("active"));
    /// ```
    #[must_use]
    pub const fn transition(target: M) -> Self {
        Self {
            change: Some(ModeChange { target }),
            commands: Vec::new(),
            _error: core::marker::PhantomData,
        }
    }

    /// Returns the mode change, if any.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// let d: Decision<&str, (), ()> = Decision::stay();
    /// assert!(d.mode_change().is_none());
    /// ```
    #[must_use]
    pub const fn mode_change(&self) -> Option<&ModeChange<M>> {
        self.change.as_ref()
    }

    /// Returns the target mode, if this decision requests a transition.
    ///
    /// This is a convenience wrapper around [`Decision::mode_change`]
    /// for the common case where you only care about the target.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// #[derive(Debug, Clone, PartialEq, Eq)]
    /// enum Mode { Ready, Active, Safe }
    ///
    /// let d: Decision<Mode, (), ()> = Decision::transition(Mode::Active);
    /// assert_eq!(d.target_mode(), Some(&Mode::Active));
    /// ```
    #[must_use]
    pub const fn target_mode(&self) -> Option<&M> {
        match &self.change {
            Some(change) => Some(&change.target),
            None => None,
        }
    }

    /// Returns the commands to execute.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// let d: Decision<(), (), ()> = Decision::stay();
    /// assert!(d.commands().is_empty());
    /// ```
    #[must_use]
    pub fn commands(&self) -> &[C] {
        &self.commands
    }

    /// Returns `true` if this decision requests a mode transition.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// let d: Decision<&str, (), ()> = Decision::transition("active");
    /// assert!(d.is_transition());
    ///
    /// let s: Decision<&str, (), ()> = Decision::stay();
    /// assert!(!s.is_transition());
    /// ```
    #[must_use]
    pub const fn is_transition(&self) -> bool {
        self.change.is_some()
    }

    /// Returns `true` if this decision stays in the current mode.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// let d: Decision<&str, (), ()> = Decision::stay();
    /// assert!(d.is_stay());
    ///
    /// let t: Decision<&str, (), ()> = Decision::transition("active");
    /// assert!(!t.is_stay());
    /// ```
    #[must_use]
    pub const fn is_stay(&self) -> bool {
        self.change.is_none()
    }

    /// Consumes the decision and returns its parts.
    ///
    /// This is useful in runtimes that own the current mode and want to move
    /// the next-mode target and commands out of the decision without cloning.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// let d: Decision<&str, &str, ()> =
    ///     Decision::transition("active").with_command("initialize");
    ///
    /// let (change, commands) = d.into_parts();
    /// assert_eq!(change.map(|mc| mc.target), Some("active"));
    /// assert_eq!(commands, vec!["initialize"]);
    /// ```
    #[must_use]
    pub fn into_parts(self) -> (Option<ModeChange<M>>, Vec<C>) {
        (self.change, self.commands)
    }

    /// Consumes the decision and returns the requested mode change, if any.
    ///
    /// Prefer [`Decision::into_parts`] if you also need the commands.
    #[must_use]
    pub fn into_mode_change(self) -> Option<ModeChange<M>> {
        self.change
    }

    /// Consumes the decision and returns its commands.
    ///
    /// Prefer [`Decision::into_parts`] if you also need the mode change.
    #[must_use]
    pub fn into_commands(self) -> Vec<C> {
        self.commands
    }

    /// Adds a command to this decision.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// let d: Decision<(), &str, ()> = Decision::stay()
    ///     .with_command("initialize");
    /// assert_eq!(d.commands(), &["initialize"]);
    /// ```
    #[must_use]
    pub fn with_command(mut self, command: C) -> Self {
        self.commands.push(command);
        self
    }

    /// Adds a command to this decision.
    ///
    /// This is an alias for [`Decision::with_command`]. It can read better in
    /// `match` arms:
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// let d: Decision<(), &str, ()> = Decision::stay().emit("log");
    /// assert_eq!(d.commands(), &["log"]);
    /// ```
    #[must_use]
    pub fn emit(self, command: C) -> Self {
        self.with_command(command)
    }

    /// Adds multiple commands to this decision.
    ///
    /// Commands are appended in iteration order.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// #[derive(Debug, Clone, PartialEq, Eq)]
    /// enum Command { Initialize, Begin }
    ///
    /// let d: Decision<(), Command, ()> =
    ///     Decision::stay().with_commands([Command::Initialize, Command::Begin]);
    /// assert_eq!(d.commands(), &[Command::Initialize, Command::Begin]);
    /// ```
    #[must_use]
    pub fn with_commands<I>(mut self, commands: I) -> Self
    where
        I: IntoIterator<Item = C>,
    {
        self.commands.extend(commands);
        self
    }

    /// Adds multiple commands to this decision.
    ///
    /// This is an alias for [`Decision::with_commands`].
    ///
    /// ```
    /// use ready_active_safe::Decision;
    ///
    /// let d: Decision<(), &str, ()> = Decision::stay().emit_all(["a", "b"]);
    /// assert_eq!(d.commands(), &["a", "b"]);
    /// ```
    #[must_use]
    pub fn emit_all<I>(self, commands: I) -> Self
    where
        I: IntoIterator<Item = C>,
    {
        self.with_commands(commands)
    }

    /// Applies this decision to an owned current mode.
    ///
    /// This is a method form of [`apply_decision`]. It tends to read well in
    /// runtime loops.
    ///
    /// ```
    /// use ready_active_safe::prelude::*;
    ///
    /// let mode = "ready";
    /// let decision: Decision<&str, &str, ()> = transition("active").emit("initialize");
    ///
    /// let (mode, commands) = decision.apply(mode);
    /// assert_eq!(mode, "active");
    /// assert_eq!(commands, vec!["initialize"]);
    /// ```
    #[must_use]
    pub fn apply(self, current_mode: M) -> (M, Vec<C>) {
        apply_decision(current_mode, self)
    }

    /// Applies this decision after checking a policy.
    ///
    /// This is a method form of [`apply_decision_checked`]. If the policy
    /// denies the transition, the mode is unchanged and commands are dropped.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::prelude::*;
    ///
    /// #[derive(Debug, Clone, PartialEq, Eq)]
    /// enum Mode { Ready, Active, Safe }
    ///
    /// struct ForwardOnly;
    /// impl Policy<Mode> for ForwardOnly {
    ///     fn is_allowed(&self, from: &Mode, to: &Mode) -> bool {
    ///         matches!((from, to), (Mode::Ready, Mode::Active) | (Mode::Active, Mode::Safe))
    ///     }
    /// }
    ///
    /// let policy = ForwardOnly;
    ///
    /// // Allowed transition
    /// let d: Decision<Mode, &str> = transition(Mode::Active).emit("go");
    /// let (mode, cmds) = d.apply_checked(Mode::Ready, &policy).unwrap();
    /// assert_eq!(mode, Mode::Active);
    /// assert_eq!(cmds, vec!["go"]);
    ///
    /// // Denied transition: mode unchanged, commands dropped
    /// let d: Decision<Mode, &str> = transition(Mode::Ready).emit("back");
    /// let err = d.apply_checked(Mode::Active, &policy).unwrap_err();
    /// assert!(matches!(err, LifecycleError::TransitionDenied { .. }));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`LifecycleError::TransitionDenied`] if the policy rejects
    /// the requested mode change.
    pub fn apply_checked<P>(
        self,
        current_mode: M,
        policy: &P,
    ) -> Result<(M, Vec<C>), LifecycleError<M>>
    where
        P: Policy<M>,
    {
        apply_decision_checked(current_mode, self, policy)
    }
}

impl<M: fmt::Display, C, E> fmt::Display for Decision<M, C, E> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match &self.change {
            Some(mc) => write!(f, "transition to {}", mc.target),
            None => write!(f, "stay"),
        }
    }
}

/// Creates a decision that stays in the current mode.
///
/// This is a free function wrapper around [`Decision::stay`]. It exists to make
/// `match` arms read like a sentence.
///
/// ```
/// use ready_active_safe::prelude::*;
///
/// #[derive(Debug, Clone, PartialEq, Eq)]
/// enum Mode {
///     Ready,
///     Active,
/// }
///
/// #[derive(Debug)]
/// enum Event {
///     Start,
/// }
///
/// #[derive(Debug, Clone, PartialEq, Eq)]
/// enum Command {
///     Log,
/// }
///
/// struct System;
///
/// impl Machine for System {
///     type Mode = Mode;
///     type Event = Event;
///     type Command = Command;
///
///     fn initial_mode(&self) -> Mode { Mode::Ready }
///
///     fn on_event(&self, mode: &Mode, event: &Event) -> Decision<Mode, Command> {
///         use Event::*;
///         use Mode::*;
///
///         match (mode, event) {
///             (Ready, Start) => transition(Active).emit(Command::Log),
///             _ => stay(),
///         }
///     }
/// }
/// ```
#[must_use]
pub const fn stay<M, C, E>() -> Decision<M, C, E> {
    Decision::stay()
}

/// Creates a decision that transitions to the given mode.
///
/// This is a free function wrapper around [`Decision::transition`]. It exists
/// to make `match` arms read like a sentence.
///
/// ```
/// use ready_active_safe::prelude::*;
///
/// let d: Decision<&str, (), ()> = transition("active");
/// assert_eq!(d.target_mode(), Some(&"active"));
/// ```
#[must_use]
pub const fn transition<M, C, E>(target: M) -> Decision<M, C, E> {
    Decision::transition(target)
}

/// Creates a decision that deliberately ignores an unmatched event.
///
/// Semantically identical to [`stay`], but communicates intent. Use
/// `ignore()` in catch-all arms to signal that silence is by design,
/// not an oversight.
///
/// ```
/// use ready_active_safe::prelude::*;
///
/// #[derive(Debug, Clone, PartialEq, Eq)]
/// enum Mode { Ready, Active }
///
/// #[derive(Debug)]
/// enum Event { Start, Ping }
///
/// struct System;
///
/// impl Machine for System {
///     type Mode = Mode;
///     type Event = Event;
///     type Command = ();
///
///     fn initial_mode(&self) -> Mode { Mode::Ready }
///
///     fn on_event(&self, mode: &Mode, event: &Event) -> Decision<Mode, ()> {
///         match (mode, event) {
///             (Mode::Ready, Event::Start) => transition(Mode::Active),
///             _ => ignore(), // deliberate: these events need no response
///         }
///     }
/// }
/// ```
#[must_use]
pub const fn ignore<M, C, E>() -> Decision<M, C, E> {
    Decision::stay()
}

/// Applies a decision to an owned current mode.
///
/// This helper is for runtimes that own the mode and want to move the target
/// mode and commands out of a [`Decision`] without cloning.
///
/// ```
/// use ready_active_safe::prelude::*;
///
/// let mode = "ready";
/// let decision: Decision<&str, &str, ()> = transition("active").emit("initialize");
///
/// let (mode, commands) = apply_decision(mode, decision);
/// assert_eq!(mode, "active");
/// assert_eq!(commands, vec!["initialize"]);
/// ```
#[must_use]
pub fn apply_decision<M, C, E>(current_mode: M, decision: Decision<M, C, E>) -> (M, Vec<C>) {
    let (change, commands) = decision.into_parts();

    let next_mode = match change {
        Some(change) => change.target,
        None => current_mode,
    };

    (next_mode, commands)
}

/// Applies a decision to an owned current mode after checking a policy.
///
/// If the decision requests a mode change and the policy denies it, this
/// returns a [`LifecycleError::TransitionDenied`] and the commands are dropped.
///
/// ```
/// use ready_active_safe::prelude::*;
///
/// #[derive(Debug, Clone, PartialEq, Eq)]
/// enum Mode {
///     Ready,
///     Active,
/// }
///
/// struct ForwardOnly;
///
/// impl Policy<Mode> for ForwardOnly {
///     fn is_allowed(&self, from: &Mode, to: &Mode) -> bool {
///         matches!((from, to), (Mode::Ready, Mode::Active))
///     }
/// }
///
/// let policy = ForwardOnly;
/// let decision: Decision<Mode, (), ()> = transition(Mode::Active);
///
/// let (mode, _commands) = apply_decision_checked(Mode::Ready, decision, &policy)?;
/// assert_eq!(mode, Mode::Active);
/// # Ok::<(), LifecycleError<Mode>>(())
/// ```
///
/// # Errors
///
/// Returns [`LifecycleError::TransitionDenied`] if the policy rejects
/// the requested mode change.
pub fn apply_decision_checked<M, C, E, P>(
    current_mode: M,
    decision: Decision<M, C, E>,
    policy: &P,
) -> Result<(M, Vec<C>), LifecycleError<M>>
where
    P: Policy<M>,
{
    let (change, commands) = decision.into_parts();

    match change {
        Some(change) => {
            let target = change.target;

            match policy.check(&current_mode, &target) {
                Ok(()) => Ok((target, commands)),
                Err(reason) => Err(LifecycleError::TransitionDenied {
                    from: current_mode,
                    to: target,
                    reason,
                }),
            }
        }
        None => Ok((current_mode, commands)),
    }
}

/// A pure function from (mode, event) to [`Decision`].
///
/// This is the central trait of the lifecycle engine. Implementations
/// define how the system responds to events in each mode. The trait
/// is deliberately minimal:
///
/// - **No `self` mutation**: `on_event` takes `&self`, ensuring the
///   machine logic is pure and deterministic.
/// - **No time parameter**: time composes via the runtime and the
///   `time` feature. The base trait stays usable without it.
/// - **No I/O**: the machine never performs side effects. It returns
///   a [`Decision`] that the runtime interprets.
///
/// # Associated Types
///
/// - `Mode`: the set of lifecycle phases (e.g., Ready, Active, Safe).
/// - `Event`: external stimuli the system can receive.
/// - `Command`: instructions for the runtime to execute.
///
/// # Type Parameter
///
/// - `E`: domain errors that can occur during event processing. Defaults to `Infallible`.
///
/// # Examples
///
/// ```
/// use ready_active_safe::prelude::*;
///
/// struct Echo;
///
/// impl Machine for Echo {
///     type Mode = ();
///     type Event = String;
///     type Command = String;
///
///     fn initial_mode(&self) {}
///
///     fn on_event(&self, _mode: &(), event: &String) -> Decision<(), String> {
///         Decision::stay().with_command(event.clone())
///     }
/// }
///
/// let echo = Echo;
/// let event = "hello".to_string();
/// let d = echo.on_event(&(), &event);
/// assert_eq!(d.commands(), &[event]);
/// ```
pub trait Machine<E = core::convert::Infallible> {
    /// The set of lifecycle modes.
    type Mode;
    /// External events that drive the system.
    type Event;
    /// Commands emitted for the runtime to execute.
    type Command;

    /// Returns the starting mode for this lifecycle.
    ///
    /// Every lifecycle has a well-defined starting point. Declaring it
    /// here keeps the definition self-contained instead of requiring
    /// the caller to know the right value.
    ///
    /// # Examples
    ///
    /// ```
    /// use ready_active_safe::prelude::*;
    ///
    /// #[derive(Debug, Clone, PartialEq, Eq)]
    /// enum Mode { Ready, Active }
    ///
    /// struct System;
    ///
    /// impl Machine for System {
    ///     type Mode = Mode;
    ///     type Event = ();
    ///     type Command = ();
    ///
    ///     fn initial_mode(&self) -> Mode { Mode::Ready }
    ///
    ///     fn on_event(&self, _: &Mode, _: &()) -> Decision<Mode, ()> {
    ///         stay()
    ///     }
    /// }
    ///
    /// let system = System;
    /// assert_eq!(system.initial_mode(), Mode::Ready);
    /// ```
    fn initial_mode(&self) -> Self::Mode;

    /// Evaluates an event in the context of the current mode.
    ///
    /// Returns a [`Decision`] describing whether the system should
    /// change mode and what commands to emit.
    fn on_event(
        &self,
        mode: &Self::Mode,
        event: &Self::Event,
    ) -> Decision<Self::Mode, Self::Command, E>;

    /// Alias for [`Machine::on_event`].
    ///
    /// This reads well in runtimes and tests.
    fn decide(
        &self,
        mode: &Self::Mode,
        event: &Self::Event,
    ) -> Decision<Self::Mode, Self::Command, E> {
        self.on_event(mode, event)
    }

    /// Returns the next mode and commands for an owned current mode.
    ///
    /// This is a convenience for runtimes that own the mode value.
    /// It is equivalent to calling `decide` and then [`Decision::apply`].
    #[must_use]
    fn step(&self, mode: Self::Mode, event: &Self::Event) -> (Self::Mode, Vec<Self::Command>) {
        self.decide(&mode, event).apply(mode)
    }

    /// Returns the next mode and commands after checking a policy.
    ///
    /// This is a convenience for runtimes that want policy checks to be
    /// explicit and centralized. It is equivalent to calling `decide` and then
    /// [`Decision::apply_checked`].
    ///
    /// # Errors
    ///
    /// Returns [`LifecycleError::TransitionDenied`] if the policy rejects
    /// the requested mode change.
    #[allow(clippy::type_complexity)]
    fn step_checked<P>(
        &self,
        mode: Self::Mode,
        event: &Self::Event,
        policy: &P,
    ) -> Result<(Self::Mode, Vec<Self::Command>), LifecycleError<Self::Mode>>
    where
        P: Policy<Self::Mode>,
    {
        self.decide(&mode, event).apply_checked(mode, policy)
    }
}

/// Determines whether a mode transition is allowed.
///
/// Policies let you enforce transition rules externally, for example by
/// ensuring that certain modes can only be reached from specific
/// predecessors. The runtime checks the policy before applying a
/// [`ModeChange`] from a [`Decision`].
///
/// **When a transition is denied**, the current mode is unchanged and
/// any commands in the decision are dropped. Plan accordingly in your
/// runtime if commands must always execute.
///
/// # Examples
///
/// ```
/// use ready_active_safe::Policy;
///
/// #[derive(Debug, PartialEq)]
/// enum Mode { Ready, Active, Safe }
///
/// struct AllowAll;
///
/// impl Policy<Mode> for AllowAll {
///     fn is_allowed(&self, _from: &Mode, _to: &Mode) -> bool {
///         true
///     }
/// }
///
/// let policy = AllowAll;
/// assert!(policy.is_allowed(&Mode::Ready, &Mode::Active));
/// ```
pub trait Policy<M> {
    /// Returns `true` if transitioning from `from` to `to` is permitted.
    fn is_allowed(&self, from: &M, to: &M) -> bool;

    /// Returns `Ok(())` if the transition is allowed, or a reason string if denied.
    ///
    /// This has a default implementation based on [`Policy::is_allowed`].
    /// Override it when you want a more specific error reason.
    ///
    /// # Errors
    ///
    /// Returns a static reason string when the transition is denied.
    fn check(&self, from: &M, to: &M) -> Result<(), &'static str> {
        if self.is_allowed(from, to) {
            Ok(())
        } else {
            Err("transition denied by policy")
        }
    }
}

/// A policy that permits every transition.
///
/// Use `AllowAll` in tests and prototypes where you do not need
/// transition restrictions. This saves writing a trivial policy impl
/// for every test file.
///
/// # Examples
///
/// ```
/// use ready_active_safe::prelude::*;
///
/// let policy = AllowAll;
/// assert!(policy.is_allowed(&"ready", &"active"));
/// assert!(policy.is_allowed(&"active", &"ready"));
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AllowAll;

impl<M> Policy<M> for AllowAll {
    fn is_allowed(&self, _from: &M, _to: &M) -> bool {
        true
    }
}

/// A policy that denies every transition.
///
/// Use `DenyAll` to test that your runtime correctly handles
/// policy denials. Every transition attempt will produce a
/// [`LifecycleError::TransitionDenied`](crate::LifecycleError::TransitionDenied).
///
/// # Examples
///
/// ```
/// use ready_active_safe::prelude::*;
///
/// let policy = DenyAll;
/// assert!(!policy.is_allowed(&"ready", &"active"));
///
/// let err = policy.check(&"ready", &"active").unwrap_err();
/// assert_eq!(err, "transition denied by policy");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DenyAll;

impl<M> Policy<M> for DenyAll {
    fn is_allowed(&self, _from: &M, _to: &M) -> bool {
        false
    }
}