Skip to main content

Crate newton_machine

Crate newton_machine 

Source
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

  1. The configuration is the type (enum XOR, struct AND).
  2. The only mutation protocol is TEA (Msg in, Cmd out).
  3. History is inertial and external (a sidecar, not live variants).
  4. 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

ModuleRole
machine / runtimeElm loop: init, update, try_apply, view
topology / transitionHarel LCA: parent tree, exit/enter, perform
andFirst-class Harel AND: And
rtc() / rtcRun-to-completion drain with a storm cap
cmd / sub / hostEffects as data; the host executes them
bits / chord / fleetHost keys: bitset projection, chord table, N runtimes (alloc)
snapshot / history{config, context, history} phase space
macrosFeature 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;alloc
pub use chord::Hit;alloc
pub use chord::MatchMode;alloc
pub use chord::Tie;alloc
pub use cmd::Cmd;
pub use cmd::CmdOverflow;
pub use cmd::INLINE_CAP;
pub use combine::Combine;
pub use fleet::Fleet;alloc
pub 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.
chordalloc
Host policy table over a Bits pool.
cmd
Commands as data. The host executes them; update never performs I/O.
combine
Associative combination of commands collected during a step.
fleetalloc
Many runtimes, one message vocabulary. Not an And of 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() using crate::IntoNode::node so authors do not name from / to twice.

Attribute Macros§

machinemacros
Fill [newton_machine::Machine] from an inherent impl that already contains init, update, and view.

Derive Macros§

IntoNodemacros
Map chart enum variants to a topology node enum by name.
Topologymacros
Parent tree on a node-id enum.