Skip to main content

Crate newtonian_core

Crate newtonian_core 

Source
Expand description

A configuration-indexed policy kernel plus the ports of a Newtonian program.

End-goal: gated hysteretic scores → exact superstate key → compiled sleeve ROM → Cmd. 0.1.0 ships a handwritten kernel (kernel): Key, Table, ScoreSpec, step_entity. Feature fold compiles YAML/TOML once into an interned ROM (no document in step). Pair with newton-machine for typed modal truth (optional feature machine: IntentionMachine for newton_machine::Runtime<M>). The optional sequencer is exec — a module, not a third crate. The host owns the pulse (tick, frame, sample) and the adapters.

The kernel sits beside the chart: step_entity does not call IntentionMachine::apply. See [[docs/adr/0020-kernel-sits-beside-the-chart]].

Hosts that already have a pulse (a test, iced, rtic, a kube reconcile) should ignore exec and call the ports themselves.

§Four kinds of live state, and a binder

People mash these into one struct. Do not.

  1. Configuration / intention — the Newton machine (IntentionMachine).
  2. Beliefs — justified, freshness-stamped world facts (BeliefStore).
  3. Mandate — standing desires / policy, not a XOR child (Mandate).
  4. Authority — what we may do to the world (Gateway).
  5. Executive — the binder, not a fifth kind of state. Optional module exec; you may be it.

§Laws this crate encodes

  • Beliefs are not context. Context is the slice of beliefs the last step needed. The store is larger and can change without a transition.
  • A belief becomes a Msg only through Lift. Ticks are not messages.
  • Effects are data. Gateway admits or refuses a Cmd; it does not live inside update.
  • Mandate changes rarely. When it changes, that is a message, not a region.
  • Kernel lookup is exact. Unauthored key → none. No longest-subset default.
  • No I/O in these traits or in step_entity. No sockets. No domain vocabulary.

rustbrain: [[docs/concepts/policy-kernel]] rustbrain: [[docs/concepts/newtonian-program]] rustbrain: [[docs/adr/0016-newtonian-core-is-the-policy-kernel]] rustbrain: [[docs/adr/0020-kernel-sits-beside-the-chart]] rustbrain: [[docs/adr/0015-two-crates-exec-is-a-module]] symbol:step_entity symbol:IntentionMachine symbol:BeliefStore symbol:Mandate symbol:Lift symbol:Gateway symbol:Executive

Re-exports§

pub use belief::MemoryStore;alloc
pub use belief::Belief;
pub use belief::BeliefStore;
pub use belief::Freshness;
pub use belief::Justification;
pub use exec::Executive;
pub use exec::PortExecutive;
pub use exec::PulseOutcome;alloc
pub use fold::Catalog;fold
pub use fold::FoldError;fold
pub use fold::KnobId;fold
pub use fold::Knobs;fold
pub use fold::Policy;fold
pub use fold::Sleeve;fold
pub use fold::KNOB_SLOTS;fold
pub use gateway::Admission;
pub use gateway::Gateway;
pub use gateway::OpenGateway;
pub use intention::IntentionMachine;
pub use intention::Step;
pub use kernel::eval_scores;
pub use kernel::specs_valid;
pub use kernel::step_entity;
pub use kernel::EntityState;
pub use kernel::Folded;
pub use kernel::KernelStep;
pub use kernel::Key;
pub use kernel::Pulse;
pub use kernel::ScoreId;
pub use kernel::ScoreSpec;
pub use kernel::Table;
pub use kernel::Transition;
pub use kernel::SCORE_WIDTH;
pub use lift::Lift;
pub use lift::Lifted;
pub use lift::Revision;
pub use mandate::EmptyMandate;
pub use mandate::Mandate;
pub use program::NoSkill;
pub use program::ProgramParts;
pub use skill::Skill;

Modules§

belief
Justified, freshness-stamped world facts.
exec
Optional Executive pulse.
foldfold
Fold: YAML/TOML → interned ROM once.
gateway
Authority. What we are allowed to do to the world.
intention
Ports a Newton machine (or any UCA host) must present to an Executive.
kernel
Configuration-indexed policy kernel.
lift
Belief × mandate × configuration → Msg or silence (or several Msgs).
mandate
Standing desires / policy. Not a state.
prelude
Types an author needs for one pulse.
program
A Newtonian program is the composition, not the loop.
skill
Tiny reflexes the Executive may run. Not chart children.