Skip to main content

newton_machine/
lib.rs

1//! Newtonian state machines: typed Harel configurations driven by an Elm loop.
2//!
3//! Unidirectional Configuration Architecture (UCA): XOR is an `enum`, AND is a
4//! `struct`, [`update`](Machine::update) is the only door, history is a sidecar,
5//! commands are data.
6//!
7//! # Four laws
8//!
9//! 1. The configuration is the type (`enum` XOR, `struct` AND).
10//! 2. The only mutation protocol is TEA (`Msg` in, `Cmd` out).
11//! 3. History is inertial and external (a sidecar, not live variants).
12//! 4. Typestate is a façade; the interior is a configuration tree.
13//!
14//! A Newton machine **may lock itself**. Only the host gateway may lock the
15//! wire. Only the venue can save you when both are dead.
16//!
17//! # Minimal machine
18//!
19//! ```
20//! use newton_machine::prelude::*;
21//!
22//! struct Chart;
23//! struct Model;
24//!
25//! impl Machine for Chart {
26//!     type Flags = ();
27//!     type Model = Model;
28//!     type Msg = ();
29//!     type Cmd = Cmd<()>;
30//!     type View = ();
31//!     type History = ();
32//!     type NodeId = &'static str;
33//!
34//!     fn init(_: ()) -> Boot<Self> {
35//!         Boot::new(Chart, Model, (), Cmd::none())
36//!     }
37//!
38//!     fn update(&mut self, _: &mut Model, _: &mut (), _: ()) -> Cmd<()> {
39//!         Cmd::none()
40//!     }
41//!
42//!     fn view(&self, _: &Model) {}
43//!
44//!     fn in_state(&self, _: &'static str) -> bool {
45//!         true
46//!     }
47//! }
48//!
49//! let (mut rt, _) = Runtime::<Chart>::boot(());
50//! let _ = rt.apply(());
51//! ```
52//!
53//! Authors of hierarchical machines implement [`Topology`] and [`Transitional`],
54//! then call [`perform()`] from [`Machine::update`]. Internal follow-ups go through
55//! [`rtc()`] (return [`Storm`] via [`Machine::try_update`]; [`unwrap_storm`]
56//! in `update`). Orthogonal regions: [`And`].
57//!
58//! GitHub carries runnable demos under `examples/` (not part of the crates.io
59//! package). See the crate README.
60//!
61//! # Macros (optional feature)
62//!
63//! Enable `macros` and read **[`macros`]** — that module is written for human
64//! authors **and** AI agents: when to use them, the copy-paste recipe, what is
65//! generated vs handwritten, and what will never be generated (`async` / I/O
66//! / a chart DSL).
67//!
68//! ```toml
69//! newton-machine = { version = "0.2", features = ["macros"] }
70//! ```
71//!
72//! Do not depend on `newton-machine-macros` directly. The git repo is a
73//! workspace; crates.io users still add **one** package.
74//!
75//! # Crate map
76//!
77//! | Module | Role |
78//! | --- | --- |
79//! | [`mod@machine`] / [`runtime`] | Elm loop: `init`, `update`, `try_apply`, `view` |
80//! | [`topology`] / [`transition`] | Harel LCA: parent tree, exit/enter, `perform` |
81//! | [`and`] | First-class Harel AND: [`And`] |
82//! | [`rtc()`] / [`mod@rtc`] | Run-to-completion drain with a storm cap |
83//! | [`cmd`] / [`sub`] / [`host`] | Effects as data; the host executes them |
84//! | [`bits`] / chord / fleet | Host keys: bitset projection, chord table, N runtimes (`alloc`) |
85//! | [`snapshot`] / [`history`] | `{config, context, history}` phase space |
86//! | [`macros`] | Feature `macros` guide (agents: start here) + re-exports of the derives |
87//!
88//! [`prelude`] re-exports the types an author needs.
89
90// rustbrain: [[docs/concepts/unidirectional-configuration-architecture]]
91// rustbrain: [[docs/concepts/newtonian-state-machine]]
92// rustbrain: [[docs/adr/0017-engine-is-topology-rtc-runtime]]
93// rustbrain: [[docs/adr/0018-cmd-inline-then-heap]]
94// rustbrain: [[docs/adr/0020-storm-panic-try-apply]]
95// rustbrain: [[docs/adr/0021-and-combinator]]
96// rustbrain: [[docs/adr/0022-sub-diff]]
97// rustbrain: [[docs/adr/0023-chord-table-is-host-policy]]
98// rustbrain: [[docs/adr/0024-macros-feature-hidden-proc-macro]]
99// symbol:Machine symbol:Runtime symbol:Outcome symbol:Snapshot symbol:perform
100
101#![no_std]
102#![cfg_attr(docsrs, feature(doc_cfg))]
103#![forbid(unsafe_code)]
104#![warn(missing_docs)]
105
106#[cfg(feature = "alloc")]
107extern crate alloc;
108
109#[cfg(feature = "std")]
110extern crate std;
111
112pub mod and;
113pub mod bits;
114#[cfg(feature = "alloc")]
115#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
116pub mod chord;
117pub mod cmd;
118pub mod combine;
119#[cfg(feature = "alloc")]
120#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
121pub mod fleet;
122pub mod history;
123pub mod host;
124pub mod machine;
125pub mod macros;
126pub mod outcome;
127pub mod prelude;
128pub mod rtc;
129pub mod runtime;
130pub mod snapshot;
131pub mod sub;
132pub mod topology;
133pub mod transition;
134
135pub use and::{And, AndHistory, AndNode};
136pub use bits::Bits;
137#[cfg(feature = "alloc")]
138pub use chord::{ChordTable, Hit, MatchMode, Tie};
139pub use cmd::{Cmd, CmdOverflow, INLINE_CAP};
140pub use combine::Combine;
141#[cfg(feature = "alloc")]
142pub use fleet::Fleet;
143pub use history::{
144    record_deep, record_shallow, restore_deep, restore_shallow, HistoryKind, HistoryStore,
145    LoadResult, MemoryStore, StoreError,
146};
147pub use host::{changed, Tape};
148pub use machine::{apply, step, try_apply, try_step, Boot, Machine};
149pub use outcome::Outcome;
150pub use rtc::{rtc, rtc_n, unwrap_storm, Inbox, Storm, DEFAULT_DRAIN_CAP};
151pub use runtime::Runtime;
152pub use snapshot::Snapshot;
153pub use sub::{Diff, Sub};
154pub use topology::{
155    ancestors, enter_path, exit_path, lca, paths, Chain, IntoNode, Paths, Topology, MAX_DEPTH,
156};
157pub use transition::{perform, Transitional};
158
159#[cfg(feature = "macros")]
160#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
161pub use newton_machine_macros::{machine, IntoNode, Topology};
162
163mod mac;