ready-active-safe 0.1.3

# User Guide

A practical guide to modeling system lifecycles with `ready-active-safe`.

This crate is a lifecycle engine, not a general purpose state machine framework.
It is meant for systems that start up, run, shut down, and recover.

## The Mental Model

Five things to know before writing code:

1. **Mode** — an operational phase (Ready, Active, Safe), not an arbitrary state.
2. **Machine** — a pure function: `(mode, event) → Decision`. No I/O, no mutation.
3. **Decision** — plain data: an optional mode change + zero or more commands.
4. **Runtime** — your code. It owns the current mode, feeds events, executes commands.
5. **Policy** — an external guard that can deny transitions before they apply.

```text
Event --> Machine::on_event(mode, event) --> Decision
                                                |-- ModeChange (optional)
                                                +-- Commands (Vec<C>)
```

The machine never performs side effects. It tells the runtime *what* to do.
The runtime decides *how* and *when* to do it.

## Quick Start

Add the crate:

```sh
cargo add ready-active-safe
```

For `no_std` core types:

```sh
cargo add ready-active-safe --no-default-features
```

Write a machine as a plain `match (mode, event)`:

```rust
use ready_active_safe::prelude::*;

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

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

#[derive(Debug, Clone, PartialEq, Eq)]
enum Command {
    Initialize,
    BeginProcessing,
    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_all([Initialize, BeginProcessing]),
            (Active, Stop | Fault) => transition(Safe)
                .emit(Shutdown),
            _ => ignore(),
        }
    }
}

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

let d = system.decide(&mode, &Event::Start);
assert_eq!(d.target_mode(), Some(&Mode::Active));
assert_eq!(d.commands(), &[Command::Initialize, Command::BeginProcessing]);

let d = system.decide(&Mode::Active, &Event::Fault);
assert_eq!(d.target_mode(), Some(&Mode::Safe));
```

That is the whole pattern.
The machine is pure, so it is easy to test.
The runtime stays outside the crate, so you can plug it into whatever environment you run in.

## Decisions

A `Decision` answers two questions:

1. Should we change mode?
2. What commands should the runtime run?

Three factory functions cover every case:

- **`transition(target)`** — move to a new mode
- **`stay()`** — remain in the current mode (event was processed, no change needed)
- **`ignore()`** — remain in the current mode (event is not relevant here)

`stay()` and `ignore()` produce identical decisions. The distinction is intent:
use `stay()` when the event was handled, and `ignore()` in catch-all arms to
signal that silence is by design, not an oversight.

```rust
use ready_active_safe::prelude::*;

// Stay in current mode
let _: Decision<&str, &str> = stay();

// Transition to a new mode
let _: Decision<&str, &str> = transition("active");

// Stay with a command
let _: Decision<&str, &str> = stay().emit("log_heartbeat");

// Transition with a command
let _: Decision<&str, &str> = transition("safe").emit("flush_buffers");

// Transition with multiple commands
let _: Decision<&str, &str> = transition("active")
    .emit_all(["initialize", "begin"]);

// Catch-all: deliberately ignore unmatched events
let _: Decision<&str, &str> = ignore();
```

### Predicates

Check what a decision does without inspecting the internals:

```rust
use ready_active_safe::prelude::*;

let d: Decision<&str, ()> = transition("active");
assert!(d.is_transition());

let d: Decision<&str, ()> = stay();
assert!(d.is_stay());
```

### stay vs ignore in practice

Use `ignore()` in catch-all arms to signal that silence is deliberate:

```rust
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
    }
}
# }
```

## Applying Decisions

In a runtime loop you usually:

1. Ask the machine for a decision
2. Apply the decision to your current mode
3. Run the commands

`Decision::apply` extracts the target mode and commands, consuming the decision.

```rust
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"]);
```

A typical runtime loop:

```rust
use ready_active_safe::prelude::*;

# #[derive(Debug, Clone, PartialEq, Eq)]
# enum Mode { Ready, Active, Safe }
# #[derive(Debug)]
# enum Event { Start, Stop }
# #[derive(Debug, Clone, PartialEq, Eq)]
# enum Command { Init, Halt }
# 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> {
#         match (mode, event) {
#             (Mode::Ready, Event::Start) => transition(Mode::Active).emit(Command::Init),
#             (Mode::Active, Event::Stop) => transition(Mode::Safe).emit(Command::Halt),
#             _ => ignore(),
#         }
#     }
# }
let system = System;
let mut mode = system.initial_mode();
let events = [Event::Start, Event::Stop];

for event in &events {
    let decision = system.decide(&mode, event);
    let (next_mode, commands) = decision.apply(mode);
    mode = next_mode;
    // dispatch commands to your runtime here
}
```

## Runtime (Runner)

If you enable the `runtime` feature (included in the default `full` feature set),
you can use `ready_active_safe::runtime::Runner` as a tiny reference loop
that owns the current mode, feeds events, applies mode changes, and returns commands.

```rust
use ready_active_safe::prelude::*;
use ready_active_safe::runtime::Runner;

# #[derive(Debug, Clone, PartialEq, Eq)]
# enum Mode { Ready, Active }
# #[derive(Debug)]
# enum Event { Start }
# #[derive(Debug, Clone, PartialEq, Eq)]
# enum Command { Init }
# 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> {
#         match (mode, event) {
#             (Mode::Ready, Event::Start) => transition(Mode::Active).emit(Command::Init),
#             _ => ignore(),
#         }
#     }
# }
let system = System;
let mut runner = Runner::new(&system);

let commands = runner.feed(&Event::Start);
assert_eq!(runner.mode(), &Mode::Active);
assert_eq!(commands, vec![Command::Init]);
```

## Policies

Sometimes a transition is valid in the machine but should be blocked in
certain deployments — for example, a safety-critical system that must
never skip the Ready phase. Policies enforce these rules externally,
without cluttering your `match` arms.

```rust
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;

assert!(policy.is_allowed(&Mode::Ready, &Mode::Active));
assert!(!policy.is_allowed(&Mode::Safe, &Mode::Ready));
```

If the policy denies the transition, the runtime does not change the mode.
It can return a `LifecycleError::TransitionDenied` instead.

### Built-In Policies

The crate ships with two policies so you do not have to write boilerplate:

```rust
use ready_active_safe::prelude::*;

// AllowAll permits every transition — ideal for tests
let policy = AllowAll;
assert!(policy.is_allowed(&"ready", &"active"));

// DenyAll denies every transition — for testing enforcement
let policy = DenyAll;
assert!(!policy.is_allowed(&"ready", &"active"));
```

Use `AllowAll` in tests where you do not care about transition restrictions.
Use `DenyAll` to verify that your runtime correctly handles denial.

## Errors

When a policy denies a transition, your runtime can surface a `LifecycleError`:

```rust
use ready_active_safe::LifecycleError;

let err: LifecycleError<&str> = LifecycleError::TransitionDenied {
    from: "safe",
    to: "ready",
    reason: "backward transitions are not allowed",
};

assert_eq!(
    err.to_string(),
    "transition denied from safe to ready: backward transitions are not allowed",
);
```

`LifecycleError` is `#[non_exhaustive]`, so keep a wildcard arm when matching:

```rust
use ready_active_safe::LifecycleError;

fn handle_error(err: LifecycleError<String>) -> String {
    match err {
        LifecycleError::TransitionDenied { from, to, reason } => {
            format!("denied: {from} -> {to} ({reason})")
        }
        _ => String::from("unknown lifecycle error"),
    }
}
```

## Testing

The crate provides assertion macros with clear failure messages.

### assert_transitions_to!

```rust
use ready_active_safe::prelude::*;
use ready_active_safe::assert_transitions_to;

let d: Decision<&str, ()> = transition("active");
assert_transitions_to!(d, "active");
```

If the decision stays instead of transitioning, the failure message says:
`"expected transition to "active", but decision stays in current mode"`

### assert_stays!

```rust
use ready_active_safe::prelude::*;
use ready_active_safe::assert_stays;

let d: Decision<&str, ()> = stay();
assert_stays!(d);
```

### assert_emits!

```rust
use ready_active_safe::prelude::*;
use ready_active_safe::assert_emits;

let d: Decision<(), &str> = stay().emit("init").emit("begin");
assert_emits!(d, ["init", "begin"]);

// Also works with no commands
let d: Decision<(), &str> = stay();
assert_emits!(d, []);
```

### Testing a Machine

Combine the macros for a complete test:

```rust
use ready_active_safe::prelude::*;
use ready_active_safe::{assert_transitions_to, assert_stays, assert_emits};

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

#[derive(Debug, Clone, PartialEq, Eq)]
enum Event { Start, Stop }

#[derive(Debug, Clone, PartialEq, Eq)]
enum Command { Init }

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> {
        match (mode, event) {
            (Mode::Ready, Event::Start) => transition(Mode::Active).emit(Command::Init),
            (Mode::Active, Event::Stop) => transition(Mode::Safe),
            _ => ignore(),
        }
    }
}

let system = System;

// Test initial mode
assert_eq!(system.initial_mode(), Mode::Ready);

// Test forward transition
let d = system.decide(&Mode::Ready, &Event::Start);
assert_transitions_to!(d, Mode::Active);
assert_emits!(d, [Command::Init]);

// Test unmatched event
let d = system.decide(&Mode::Safe, &Event::Start);
assert_stays!(d);
```

## Time

The base `Machine` trait does not include a clock parameter.
Time enters through events — your runtime emits tick or timeout events,
and the machine decides based on them.

The `time` feature provides `Clock`, `Instant`, and `Deadline` types.
`ManualClock` makes time deterministic in tests; `SystemClock` uses real
monotonic time in production.

```rust
use ready_active_safe::prelude::*;
use ready_active_safe::time::{Clock, Deadline, Instant, ManualClock};
use core::time::Duration;

// ManualClock: you control time, perfect for tests
let clock = ManualClock::new(Instant::from_nanos(0));
let deadline = Deadline::at(Instant::from_nanos(1_000_000_000)); // 1 second

assert!(!deadline.is_expired(clock.now()));

clock.advance(Duration::from_millis(500));
assert!(!deadline.is_expired(clock.now()));

clock.advance(Duration::from_millis(500));
assert!(deadline.is_expired(clock.now()));
```

A machine that uses time typically receives it through its event type:

```rust
use ready_active_safe::prelude::*;
use ready_active_safe::time::{Clock, Instant, ManualClock};

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

#[derive(Debug)]
enum Event {
    Start,
    Tick(Instant),
}

#[derive(Debug, Clone, PartialEq, Eq)]
enum Command { Begin }

struct System { timeout: Instant }

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> {
        match (mode, event) {
            (Mode::Ready, Event::Start) => transition(Mode::Active).emit(Command::Begin),
            (Mode::Active, Event::Tick(now)) if *now >= self.timeout => {
                transition(Mode::TimedOut)
            }
            _ => ignore(),
        }
    }
}

// Test with deterministic time
let system = System { timeout: Instant::from_nanos(5_000_000_000) };
let clock = ManualClock::new(Instant::from_nanos(0));

let d = system.decide(&Mode::Active, &Event::Tick(clock.now()));
assert!(d.is_stay()); // not timed out yet

clock.advance(core::time::Duration::from_secs(6));
let d = system.decide(&Mode::Active, &Event::Tick(clock.now()));
assert_eq!(d.target_mode(), Some(&Mode::TimedOut)); // expired
```

## Journal

If you enable the `journal` feature, you can record transitions as data so you can replay
and audit what happened. The journal is an observer: it does not modify decisions.

```rust
use ready_active_safe::prelude::*;
use ready_active_safe::journal::InMemoryJournal;

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

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

#[derive(Debug, Clone, PartialEq, Eq)]
enum Command { Init }

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> {
        match (mode, event) {
            (Mode::Ready, Event::Start) => transition(Mode::Active).emit(Command::Init),
            _ => ignore(),
        }
    }
}

let system = System;
let mut mode = system.initial_mode();
let mut journal = InMemoryJournal::new();

let event = Event::Start;
let decision = system.decide(&mode, &event);
let (next_mode, commands) = decision.clone().apply(mode.clone());

journal.record_step(&mode, &next_mode, &event, decision.commands());
mode = next_mode;

assert_eq!(mode, Mode::Active);
assert_eq!(commands, vec![Command::Init]);
assert_eq!(journal.len(), 1);

let replay_mode = journal.replay(&system, system.initial_mode()).unwrap();
assert_eq!(replay_mode, Mode::Active);
```

## Feature Flags Reference

### Selecting Features

```toml
# Full feature set (default)
ready-active-safe = "0.1"

# Core types only, no_std compatible
ready-active-safe = { version = "0.1", default-features = false }

# Core types + time (no_std compatible)
ready-active-safe = { version = "0.1", default-features = false, features = ["time"] }

# Standard library + runtime (no journal)
ready-active-safe = { version = "0.1", default-features = false, features = ["runtime"] }
```

### Feature Dependency Graph

```text
full -----> std
       |--> runtime -----> std
       |--> time
       |--> journal -----> std
```

### Compatibility Matrix

| Configuration                  | `no_std` | `alloc` Required | Available Types                               |
|--------------------------------|----------|------------------|-----------------------------------------------|
| `--no-default-features`        | Yes      | Yes              | `Machine`, `Decision`, `ModeChange`, `Policy`, `AllowAll`, `DenyAll`, `LifecycleError`, macros |
| `--features time`              | Yes      | Yes              | Above + `time` module                         |
| `--features std`               | No       | Yes              | Above + `std::error::Error` impls             |
| `--features runtime`           | No       | Yes              | Above + `std` + `runtime` module              |
| `--features journal`           | No       | Yes              | Above + `std` + `journal` module              |
| `--all-features` or default    | No       | Yes              | Everything                                    |