Skip to main content

newtonian_core/
lib.rs

1//! A configuration-indexed **policy kernel** plus the ports of a Newtonian program.
2//!
3//! End-goal: gated hysteretic scores → exact superstate key → compiled sleeve
4//! ROM → `Cmd`. `0.1.0` ships a **handwritten** kernel ([`kernel`]):
5//! [`Key`], [`Table`], [`ScoreSpec`], [`step_entity`]. Feature `fold` compiles
6//! YAML/TOML **once** into an interned ROM (no document in `step`). Pair with
7//! `newton-machine` for typed
8//! modal truth (optional feature `machine`: [`IntentionMachine`] for
9//! `newton_machine::Runtime<M>`). The optional sequencer is [`exec`] — a
10//! **module**, not a third crate. The host owns the pulse (tick, frame, sample)
11//! and the adapters.
12//!
13//! The kernel sits **beside** the chart: [`step_entity`] does not call
14//! [`IntentionMachine::apply`]. See [[docs/adr/0020-kernel-sits-beside-the-chart]].
15//!
16//! Hosts that already have a pulse (a test, iced, rtic, a kube reconcile)
17//! should ignore [`exec`] and call the ports themselves.
18//!
19//! # Four kinds of live state, and a binder
20//!
21//! People mash these into one struct. Do not.
22//!
23//! 1. **Configuration / intention** — the Newton machine (`IntentionMachine`).
24//! 2. **Beliefs** — justified, freshness-stamped world facts (`BeliefStore`).
25//! 3. **Mandate** — standing desires / policy, not a XOR child (`Mandate`).
26//! 4. **Authority** — what we may do to the world (`Gateway`).
27//! 5. **Executive** — the binder, not a fifth kind of state. Optional module
28//!    [`exec`]; you may *be* it.
29//!
30//! # Laws this crate encodes
31//!
32//! - Beliefs are not context. Context is the slice of beliefs the last step
33//!   needed. The store is larger and can change without a transition.
34//! - A belief becomes a `Msg` only through [`Lift`]. Ticks are not messages.
35//! - Effects are data. [`Gateway`] admits or refuses a `Cmd`; it does not live
36//!   inside `update`.
37//! - Mandate changes rarely. When it changes, that is a message, not a region.
38//! - Kernel lookup is exact. Unauthored key → none. No longest-subset default.
39//! - No I/O in these traits or in [`step_entity`]. No sockets. No domain vocabulary.
40//!
41//! rustbrain: [[docs/concepts/policy-kernel]]
42//! rustbrain: [[docs/concepts/newtonian-program]]
43//! rustbrain: [[docs/adr/0016-newtonian-core-is-the-policy-kernel]]
44//! rustbrain: [[docs/adr/0020-kernel-sits-beside-the-chart]]
45//! rustbrain: [[docs/adr/0015-two-crates-exec-is-a-module]]
46//! symbol:step_entity symbol:IntentionMachine symbol:BeliefStore symbol:Mandate symbol:Lift symbol:Gateway symbol:Executive
47
48#![no_std]
49#![cfg_attr(docsrs, feature(doc_cfg))]
50#![forbid(unsafe_code)]
51#![warn(missing_docs)]
52
53#[cfg(feature = "alloc")]
54extern crate alloc;
55
56#[cfg(feature = "std")]
57extern crate std;
58
59pub mod belief;
60pub mod exec;
61#[cfg(feature = "fold")]
62pub mod fold;
63pub mod gateway;
64pub mod intention;
65pub mod kernel;
66pub mod lift;
67pub mod mandate;
68pub mod prelude;
69pub mod program;
70pub mod skill;
71
72#[cfg(feature = "machine")]
73mod machine_port;
74
75#[cfg(feature = "alloc")]
76pub use belief::MemoryStore;
77pub use belief::{Belief, BeliefStore, Freshness, Justification};
78pub use exec::Executive;
79pub use exec::PortExecutive;
80#[cfg(feature = "alloc")]
81pub use exec::PulseOutcome;
82#[cfg(feature = "fold")]
83pub use fold::{Catalog, FoldError, KnobId, Knobs, Policy, Sleeve, KNOB_SLOTS};
84pub use gateway::{Admission, Gateway, OpenGateway};
85pub use intention::{IntentionMachine, Step};
86pub use kernel::{
87    eval_scores, specs_valid, step_entity, EntityState, Folded, KernelStep, Key, Pulse, ScoreId,
88    ScoreSpec, Table, Transition, SCORE_WIDTH,
89};
90pub use lift::{Lift, Lifted, Revision};
91pub use mandate::{EmptyMandate, Mandate};
92pub use program::{NoSkill, ProgramParts};
93pub use skill::Skill;