evorule_reactor/lib.rs
1// SPDX-License-Identifier: AGPL-3.0-or-later
2// Copyright (C) 2026 EvoRule Project
3// This file is part of EvoRule, licensed under GNU Affero General Public License v3 or later.
4//! EvoRule 反应式执行器
5//!
6//! # 设计原则
7//! - 事实驱动:所有交互通过 Fact 通道进行
8//! - 单一串行通道:保证调度确定性
9//! - 稳定检测:队列空 + 无待处理 I/O = 稳定
10//! - 无状态泄漏:所有状态由反应器维护
11//! - Append-Only 审计链:所有 Fact 追加到 FactsLog,支持审计重放
12//!
13//! # 架构
14//! ```text
15//! 用户/治理层 → FactSender → [command mpsc] → 反应器
16//! ↓
17//! 调用 TCB 核心
18//! ↓
19//! 产生新 Fact → event broadcast → 用户/I/O 订阅者/审计器
20//! ↓
21//! 所有 Fact → FactsLog(审计链)
22//! ```
23//!
24//! # 模块结构
25//! - `fact` — Fact 枚举、FactId、IoType
26//! - `io_handler` — I/O Handler trait(H5: 从 evorule-governance 下沉,object-safe)
27//! - `channel` — 双通道封装(command + event)
28//! - `reactor` — 反应器核心引擎
29//! - `state` — 反应器内部状态
30//! - `facts_log` — Append-Only 审计链(含哈希链)
31//! - `stable_detector` — 稳定检测逻辑
32//! - `invariants` — 结构不变量检查
33//! - `hash` — BLAKE3 哈希链算法(单一真相源)
34//! - `wal` — WAL 读写(JSONL 格式,含哈希字段)
35//! - `pure` — 纯逻辑模块,Kani 形式化验证准备
36//! - `runtime` — 运行时抽象(时钟缝:宿主能力隔离到 trait 之后)
37//! - `ffi` — C FFI 接口(feature = "ffi")
38//! - `error` — 错误类型定义
39//! - `phase` — 反应器阶段定义
40//!
41//! # 使用示例
42//! ```ignore
43//! use evorule_reactor::{Reactor, Fact, FactId};
44//! use evorule_tcb::JsonValue;
45//!
46//! let core_eval = vec![]; // 从 core_eval.json 加载
47//! let reactor = Reactor::builder(core_eval).max_rounds(1000).build();
48//! let (tx, mut rx, _event_tx, _handle, _facts_log) = reactor.spawn();
49//!
50//! // 提交命令
51//! tx.send(Fact::Command {
52//! id: FactId(1),
53//! instruction: JsonValue::object_from_pairs(&[
54//! ("type", JsonValue::string("increment")),
55//! ("params", JsonValue::object_from_pairs(&[
56//! ("attr", JsonValue::string("x")),
57//! ("delta", JsonValue::Integer(5)),
58//! ])),
59//! ]),
60//! }).unwrap();
61//!
62//! // 等待 Stable 事实(broadcast recv 返回 Result)
63//! while let Ok(fact) = rx.recv().await {
64//! if let Fact::Stable { version, .. } = fact {
65//! println!("会话于版本 {} 稳定", version);
66//! break;
67//! }
68//! }
69//! ```
70
71#![deny(unsafe_code)]
72#![deny(missing_docs)]
73// 永不 panic 保障:禁止以下 panic-prone 模式(与 evorule-tcb 基线对齐)
74// 测试/基准模块内可局部 #[allow(...)] 豁免
75#![deny(clippy::unwrap_used)]
76#![deny(clippy::expect_used)]
77#![deny(clippy::indexing_slicing)]
78#![deny(clippy::panic)]
79
80mod channel;
81mod channel_local;
82mod error;
83mod fact;
84mod facts_log;
85// ffi feature 必须暴露 extern "C" 接口,局部 allow unsafe_code 覆盖 deny
86// 默认 feature (无 ffi) 下 ffi 模块不会被编译
87#[cfg_attr(feature = "ffi", allow(unsafe_code))]
88#[cfg(feature = "ffi")]
89mod ffi;
90mod hash;
91mod invariants;
92// H5: IoHandler trait 下沉到 evorule-reactor(与 IoType 同层,object-safe)
93mod io_context;
94mod io_dispatcher;
95mod io_handler;
96mod phase;
97#[allow(dead_code)]
98mod pure;
99mod reactor;
100mod runtime;
101mod stable_detector;
102mod state;
103#[cfg(feature = "persistence")]
104mod wal;
105
106pub use channel::{ChannelPair, EventReceiver, EventSender, FactReceiver, FactSender};
107pub use channel_local::{
108 local_broadcaster, local_pair, LocalEventReceiver, LocalEventSender, LocalReceiver, LocalSender,
109};
110pub use error::ReactorError;
111pub use fact::{ControlFlowType, Fact, FactId, FactIdGenerator, IoType, TraceHit};
112// H5: IoHandler/IoResult 从 evorule-governance 下沉,供应用层 crate 使用
113#[cfg(feature = "persistence")]
114pub use facts_log::replay_wal_records;
115pub use facts_log::{FactsLog, FactsLogError};
116pub use hash::{
117 chain_step, compute_chain_hash, content_hash, fact_hash, fact_to_stable_json, HashError,
118};
119pub use invariants::InvariantViolation;
120pub use io_context::{CallerRole, CallerRoleResolver, IoCallContext};
121pub use io_dispatcher::{IoDispatcher, IoDispatcherBuilder};
122pub use io_handler::{IoHandler, IoResult};
123pub use phase::{PhaseContext, ReactorPhase};
124pub use reactor::{
125 InvariantScanReport, PendingIoEntry, Reactor, ReactorBuilder, ReactorHandle,
126 ReactorStateSnapshot,
127};
128pub use runtime::{ClockHandle, FixedClock, RuntimeClock, SystemClock};
129pub use stable_detector::StableDetector;
130#[cfg(feature = "persistence")]
131pub use wal::{
132 fact_from_json, fact_to_json, parse_wal_records, read_wal, read_wal_with_hash, serde_to_tcb,
133 tcb_to_serde, FactWalStore, MemoryWalStore, WalError, WalRecord, WalWriter,
134};