Expand description
Newtonian state machines: typed Harel configurations driven by an Elm loop.
Unidirectional Configuration Architecture (UCA): XOR is an enum, AND is a
struct, update is the only door, history is a sidecar,
commands are data.
§Four laws
- The configuration is the type (
enumXOR,structAND). - The only mutation protocol is TEA (
Msgin,Cmdout). - History is inertial and external (a sidecar, not live variants).
- Typestate is a façade; the interior is a configuration tree.
A Newton machine may lock itself. Only the host gateway may lock the wire. Only the venue can save you when both are dead.
§Minimal machine
use newton_machine::prelude::*;
struct Chart;
struct Model;
impl Machine for Chart {
type Flags = ();
type Model = Model;
type Msg = ();
type Cmd = Cmd<()>;
type View = ();
type History = ();
type NodeId = &'static str;
fn init(_: ()) -> Boot<Self> {
Boot::new(Chart, Model, (), Cmd::none())
}
fn update(&mut self, _: &mut Model, _: &mut (), _: ()) -> Cmd<()> {
Cmd::none()
}
fn view(&self, _: &Model) {}
fn in_state(&self, _: &'static str) -> bool {
true
}
}
let (mut rt, _) = Runtime::<Chart>::boot(());
let _ = rt.apply(());Authors of hierarchical machines implement Topology and Transitional,
then call perform() from Machine::update. Internal follow-ups go through
rtc() (return Storm via Machine::try_update; unwrap_storm
in update). Orthogonal regions: And.
GitHub carries runnable demos under examples/ (not part of the crates.io
package). See the crate README.
§Macros (optional feature)
Enable macros and read macros — that module is written for human
authors and AI agents: when to use them, the copy-paste recipe, what is
generated vs handwritten, and what will never be generated (async / I/O
/ a chart DSL).
newton-machine = { version = "0.2", features = ["macros"] }Do not depend on newton-machine-macros directly. The git repo is a
workspace; crates.io users still add one package.
§Crate map
| Module | Role |
|---|---|
machine / runtime | Elm loop: init, update, try_apply, view |
topology / transition | Harel LCA: parent tree, exit/enter, perform |
and | First-class Harel AND: And |
rtc() / rtc | Run-to-completion drain with a storm cap |
cmd / sub / host | Effects as data; the host executes them |
bits / chord / fleet | Host keys: bitset projection, chord table, N runtimes (alloc) |
snapshot / history | {config, context, history} phase space |
macros | Feature macros guide (agents: start here) + re-exports of the derives |
prelude re-exports the types an author needs.
Re-exports§
pub use and::And;pub use and::AndHistory;pub use and::AndNode;pub use bits::Bits;pub use chord::ChordTable;allocpub use chord::Hit;allocpub use chord::MatchMode;allocpub use chord::Tie;allocpub use cmd::Cmd;pub use cmd::CmdOverflow;pub use cmd::INLINE_CAP;pub use combine::Combine;pub use fleet::Fleet;allocpub use history::record_deep;pub use history::record_shallow;pub use history::restore_deep;pub use history::restore_shallow;pub use history::HistoryKind;pub use history::HistoryStore;pub use history::LoadResult;pub use history::MemoryStore;pub use history::StoreError;pub use host::changed;pub use host::Tape;pub use machine::apply;pub use machine::step;pub use machine::try_apply;pub use machine::try_step;pub use machine::Boot;pub use machine::Machine;pub use outcome::Outcome;pub use rtc::rtc;pub use rtc::rtc_n;pub use rtc::unwrap_storm;pub use rtc::Inbox;pub use rtc::Storm;pub use rtc::DEFAULT_DRAIN_CAP;pub use runtime::Runtime;pub use snapshot::Snapshot;pub use sub::Diff;pub use sub::Sub;pub use topology::ancestors;pub use topology::enter_path;pub use topology::exit_path;pub use topology::lca;pub use topology::paths;pub use topology::Chain;pub use topology::IntoNode;pub use topology::Paths;pub use topology::Topology;pub use topology::MAX_DEPTH;pub use transition::perform;pub use transition::Transitional;
Modules§
- and
- First-class Harel AND: two machines, one message, one RTC clock.
- bits
- Compact configuration key. Not a Harel node, not a string id.
- chord
alloc - Host policy table over a
Bitspool. - cmd
- Commands as data. The host executes them;
updatenever performs I/O. - combine
- Associative combination of commands collected during a step.
- fleet
alloc - Many runtimes, one message vocabulary. Not an
Andof N machines. - history
- History as a sidecar, not as live configuration.
- host
- Host-side helpers. The crate still never opens a socket.
- machine
- Elm loop around a Harel configuration tree.
- macros
- Feature
macros: what an author (or AI agent) enables, writes, and gets back. - outcome
- Per-region dispatch result. Parents see
Super; the step sees a transition. - prelude
- Common imports for authors of a Newton machine.
- rtc
- Run-to-completion drain of internal follow-up messages.
- runtime
- Owns
{config, context, history}and runs the Elm loop. - snapshot
- Phase-space point of a Newton machine:
{config, context, history}. - sub
- Subscriptions as data. Listeners exist only while the configuration needs them.
- topology
- Chart tree as node ids: parent, LCA, exit and enter paths.
- transition
- LCA transition: exit inner-first, install destination, enter outer-first.
Macros§
- perform
- LCA
crate::perform()usingcrate::IntoNode::nodeso authors do not namefrom/totwice.
Attribute Macros§
- machine
macros - Fill [
newton_machine::Machine] from an inherentimplthat already containsinit,update, andview.