Crate ready_active_safe 

ready-active-safe

A small lifecycle engine for externally driven systems.

Most real systems do not have an “anything can go anywhere” state graph. They have a lifecycle. They start up, run, and shut down. When things go wrong, they go safe and recover.

This crate gives you a tiny kernel for that shape of problem. You write one pure function, Machine::on_event, and you get back a Decision. The decision is plain data, not effects. Your runtime stays yours.

This crate is not a general purpose state machine framework. It is a lifecycle engine.

What You Write

• Mode: lifecycle phases like Ready, Active, Safe
• Event: input from the outside world
• Command: work for your runtime to execute

Feature Flags

Feature	Default	Requires	Description
full	Yes	none	Enables all features below
std	No*	none	Standard library support
runtime	No*	std	Event loop and command dispatch
time	No*	none	Clock, instant, and deadline types
journal	No*	std	Transition recording and replay

*Enabled by default through the full feature.

Module Overview

• Root types (Machine, Decision, ModeChange, Policy): Always available, no_std-compatible. These are the core contracts.
• LifecycleError: transition failure errors.
• time (feature time): Clock and deadline abstractions.
• runtime (feature runtime): Event acceptance and command dispatch.
• journal (feature journal): Transition recording and replay.

Examples

Run any example with cargo run --example <name>. Suggested reading order:

1. basic — core API: Machine, Decision, stay(), transition(), emit()
2. openxr_session — real-world domain mapping (XR session lifecycle)
3. recovery — Policy enforcement and apply_checked
4. runner — Runner event loop with policy denial handling
5. recovery_cycle — repeated fault/recovery with external retry logic
6. channel_runtime — multi-threaded event feeding over channels
7. metrics — observability wrapper around Runner
8. replay — journal recording and deterministic replay

Quick Start

use ready_active_safe::prelude::*;

#[derive(Debug, Clone, PartialEq, Eq)]
enum Mode {
    Ready,
    Active,
    Safe,
}

#[derive(Debug)]
enum Event {
    Start,
    Stop,
    Fault,
}

#[derive(Debug)]
enum Command {
    Initialize,
    Shutdown,
}

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 Command::*;
        use Event::*;
        use Mode::*;

        match (mode, event) {
            (Ready, Start) => transition(Active).emit(Initialize),
            (Active, Stop | Fault) => transition(Safe).emit(Shutdown),
            _ => ignore(),
        }
    }
}

let system = System;
let mut mode = system.initial_mode();

let decision = system.decide(&mode, &Event::Start);
assert!(decision.is_transition());
assert_eq!(decision.target_mode(), Some(&Mode::Active));

Modules

journaljournal

Transition recording and deterministic replay.

prelude

Convenience re-exports for common imports.

runtimeruntime

A small reference runtime.

timetime

Clock, instant, and deadline abstractions for lifecycle timing.

Macros

assert_emits

Asserts that a decision emits the expected commands.

assert_stays

Asserts that a decision stays in the current mode.

assert_transitions_to

Asserts that a decision transitions to the expected mode.

Structs

AllowAll

A policy that permits every transition.

Decision

The outcome of processing an event through Machine::on_event.

DenyAll

A policy that denies every transition.

ModeChange

A requested change from one mode to another.

Enums

LifecycleError

Errors that can occur during lifecycle operations.

Traits

Machine

A pure function from (mode, event) to Decision.

Policy

Determines whether a mode transition is allowed.

Functions

apply_decision

Applies a decision to an owned current mode.

apply_decision_checked

Applies a decision to an owned current mode after checking a policy.

ignore

Creates a decision that deliberately ignores an unmatched event.

stay

Creates a decision that stays in the current mode.

transition

Creates a decision that transitions to the given mode.