arkhe_kernel/
lib.rs

1#![forbid(unsafe_code)]
2#![warn(missing_docs)]
3
4//! # ArkheKernel
5//!
6//! Deterministic microkernel for virtual worlds. The kernel is a pure
7//! state machine: identical inputs always produce identical state and
8//! identical persisted bytes. There is no `async`, no `std::thread`, no
9//! `unsafe`, no floating-point in canonical paths, and no
10//! `HashMap`/`HashSet` (only `BTreeMap`/`BTreeSet` for deterministic
11//! iteration).
12//!
13//! ## Layered DAG
14//!
15//! ```text
16//! abi  →  state  →  runtime  →  persist
17//! ```
18//!
19//! Downward-only via `pub(crate)` edges; cross-stratum back-edges are a
20//! structural error caught by the layer-DAG CI gate (R4-X).
21//!
22//! - [`abi`] — identifiers, principals, capability bits, the
23//!   [`abi::ArkheError`] taxonomy.
24//! - [`state`] — sealed traits ([`state::Action`], [`state::Component`],
25//!   [`state::Event`]), per-instance state, authorization phantoms
26//!   ([`state::Effect`]).
27//! - [`runtime`] — orchestrator [`Kernel`], step-stage commit-or-rollback,
28//!   observer pipeline, read-only [`InstanceView`].
29//! - [`persist`] — [`Wal`] (BLAKE3-keyed chain),
30//!   [`KernelSnapshot`] (postcard blob), [`SignatureClass`] (Ed25519
31//!   Tier 2 + Hybrid PQC ML-DSA 65), [`replay_into`](persist::replay_into).
32//!
33//! ## Quick start
34//!
35//! Domains define an `Action` via the `#[derive(ArkheAction)]` macro
36//! plus `impl ActionCompute`, register it on the kernel, submit it,
37//! and step the clock. The kernel does the rest:
38//!
39//! ```
40//! use arkhe_kernel::abi::{CapabilityMask, EntityId, Principal, Tick, TypeCode};
41//! use arkhe_kernel::state::{ActionCompute, ActionContext, InstanceConfig, Op};
42//! use arkhe_kernel::{ArkheAction, Kernel};
43//! use serde::{Deserialize, Serialize};
44//!
45//! #[derive(Serialize, Deserialize, ArkheAction)]
46//! #[arkhe(type_code = 1, schema_version = 1)]
47//! struct Hello;
48//!
49//! impl ActionCompute for Hello {
50//!     fn compute(&self, _ctx: &ActionContext) -> Vec<Op> {
51//!         vec![Op::SpawnEntity {
52//!             id: EntityId::new(1).unwrap(),
53//!             owner: Principal::System,
54//!         }]
55//!     }
56//! }
57//!
58//! let mut kernel = Kernel::new();
59//! kernel.register_action::<Hello>();
60//! let inst = kernel.create_instance(InstanceConfig::default());
61//! kernel.submit(inst, Principal::System, None, Tick(0), TypeCode(1), Vec::new()).unwrap();
62//! let report = kernel.step(Tick(0), CapabilityMask::SYSTEM);
63//! assert_eq!(report.actions_executed, 1);
64//! assert_eq!(report.effects_applied, 1);
65//! ```
66//!
67//! ## Determinism guarantees
68//!
69//! - **A1 D1-Total** — identical config + identical postcard-canonical
70//!   input sequence + identical `ModuleManifest` produces bit-identical
71//!   WAL records (BLAKE3 chain), bit-identical snapshots, and identical
72//!   step counters. The dice domain demonstrates this end-to-end.
73//! - **A2 single-thread** — `Kernel: !Sync` via `PhantomData<Rc<()>>`.
74//! - **A12 panic-free** — every kernel-internal Drop is total; no
75//!   reachable panic in production code paths (test fixtures excepted).
76//! - **A14 header pinning** — WAL header carries kernel semver, ABI
77//!   version, postcard version, BLAKE3 version, world id, manifest digest.
78//!   Replay against an incompatible header is a structural error, not a
79//!   runtime surprise.
80//!
81//! See `book/src/en/architecture/invariants.md` for the full axiom
82//! list (A1–A24 + S1).
83//!
84//! ## Stability
85//!
86//! v0.13 — single fixed pre-public version (no version bumps before
87//! public release). Version 1.0 is intentionally never reached.
88
89/// L0 ABI stratum — identifiers, authority principals, capability
90/// bits, and the top-level [`abi::ArkheError`] type. No dependencies
91/// on state / runtime / persist strata.
92pub mod abi;
93
94/// L0 state stratum — sealed traits ([`Action`](state::Action),
95/// [`Component`](state::Component), [`Event`](state::Event)),
96/// authorization phantoms, per-instance state container.
97pub mod state;
98
99/// L0 runtime stratum — kernel orchestrator, step-stage commit
100/// machinery, observer pipeline, [`InstanceView`] read API.
101pub mod runtime;
102
103/// L0 persist stratum — [`Wal`], [`KernelSnapshot`],
104/// [`SignatureClass`], and the [`replay_into`](persist::replay_into)
105/// reconstruction path.
106pub mod persist;
107
108pub use persist::{
109    KernelSnapshot, ReplayError, ReplayReport, SignatureClass, SnapshotError, Wal, WalError,
110    WalHeader, WalRecord, WalWriter,
111};
112pub use runtime::event::{EventMask, KernelEvent, ObserverHandle};
113pub use runtime::{InstanceView, Kernel, KernelObserver, Stats, StepReport};
114
115/// Re-export of the kernel-companion derive macros. `ArkheAction`
116/// emits `Sealed + ActionDeriv` (pair with `impl ActionCompute`).
117/// `ArkheComponent` and `ArkheEvent` emit `Sealed +` the corresponding
118/// kernel trait — postcard-canonical defaults handle the byte round
119/// trip. Every derive expects `#[arkhe(type_code = N, schema_version = M)]`.
120pub use arkhe_macros::{ArkheAction, ArkheComponent, ArkheEvent};
arkhe_kernel/lib.rs

arkhe_kernel/
lib.rs
