Expand description
EvoRule 反应式执行器
§设计原则
- 事实驱动:所有交互通过 Fact 通道进行
- 单一串行通道:保证调度确定性
- 稳定检测:队列空 + 无待处理 I/O = 稳定
- 无状态泄漏:所有状态由反应器维护
- Append-Only 审计链:所有 Fact 追加到 FactsLog,支持审计重放
§架构
用户/治理层 → FactSender → [command mpsc] → 反应器
↓
调用 TCB 核心
↓
产生新 Fact → event broadcast → 用户/I/O 订阅者/审计器
↓
所有 Fact → FactsLog(审计链)§模块结构
fact— Fact 枚举、FactId、IoTypeio_handler— I/O Handler trait(H5: 从 evorule-governance 下沉,object-safe)channel— 双通道封装(command + event)reactor— 反应器核心引擎state— 反应器内部状态facts_log— Append-Only 审计链(含哈希链)stable_detector— 稳定检测逻辑invariants— 结构不变量检查hash— BLAKE3 哈希链算法(单一真相源)wal— WAL 读写(JSONL 格式,含哈希字段)pure— 纯逻辑模块,Kani 形式化验证准备runtime— 运行时抽象(时钟缝:宿主能力隔离到 trait 之后)ffi— C FFI 接口(feature = “ffi”)error— 错误类型定义phase— 反应器阶段定义
§使用示例
ⓘ
use evorule_reactor::{Reactor, Fact, FactId};
use evorule_tcb::JsonValue;
let core_eval = vec![]; // 从 core_eval.json 加载
let reactor = Reactor::builder(core_eval).max_rounds(1000).build();
let (tx, mut rx, _event_tx, _handle, _facts_log) = reactor.spawn();
// 提交命令
tx.send(Fact::Command {
id: FactId(1),
instruction: JsonValue::object_from_pairs(&[
("type", JsonValue::string("increment")),
("params", JsonValue::object_from_pairs(&[
("attr", JsonValue::string("x")),
("delta", JsonValue::Integer(5)),
])),
]),
}).unwrap();
// 等待 Stable 事实(broadcast recv 返回 Result)
while let Ok(fact) = rx.recv().await {
if let Fact::Stable { version, .. } = fact {
println!("会话于版本 {} 稳定", version);
break;
}
}Structs§
- Channel
Pair - 双通道对(command mpsc + event broadcast)
- Clock
Handle - 时钟句柄:引擎持有的
RuntimeClock共享指针 - FactId
- 事实唯一标识符
- Fact
IdGenerator - 事实 ID 生成器(单调递增)
- Facts
Log - Append-Only 事实审计链
- Fixed
Clock - 固定时钟(测试与确定性验证用)
- Hash
Error - 哈希计算错误类型
- Invariant
Scan Report - 最近一轮不变式扫描报告(每迭代头随内置自检刷新)
- IoCall
Context - I/O 调用上下文 —— 权限判定与审计对齐的信息载体
- IoDispatcher
- I/O 分发器(机制层)
- IoDispatcher
Builder - I/O 分发器 builder(链式注册)
- IoType
- I/O 请求类型(与 core_eval.json 中的 io_type 对应)
- Local
Event Receiver - 单线程 event 接收端(每订阅者独立队列)
- Local
Event Sender - 单线程 event 发送端(broadcast 语义:多订阅者、各自独立队列、新订阅者不收历史)
- Local
Receiver - 单线程 command 接收端(单消费者 FIFO)
- Local
Sender - 单线程 command 发送端(unbounded mpsc 语义,可克隆共享同一队列)
- Pending
IoEntry - 阶段6:pending I/O 详情条目(snapshot 中单个 I/O 请求的状态)
- Phase
Context - 阶段转移上下文(纯数据,用于转移函数判断)
- Reactor
- 反应器实例
- Reactor
Builder - 反应器配置构建器
- Reactor
Handle - 反应器任务句柄
- Reactor
State Snapshot - 反应器状态快照(只读访问,供 tier2 查询)
- Stable
Detector - 稳定检测器
- System
Clock - 系统时钟(native 默认后端)
- Trace
Hit - 单条规则命中归因的 trace 条目
Enums§
- Caller
Role - 调用者角色 —— 调用时“代表谁“(区别于规则
author:author 表示“谁写的“) - Control
Flow Type - 控制流指令类型(G8 合规:唯一真值来源,位于 fact.rs 受豁免)
- Fact
- 事实(Fact)—— 系统的原子通信单元
- Facts
LogError - FactsLog 错误类型
- Invariant
Violation - 不变式违规
- Reactor
Error - 反应器错误
- Reactor
Phase - 反应器执行阶段
Traits§
- IoHandler
- I/O Handler trait —— 所有 I/O handler 实现此接口
- Runtime
Clock - 时钟抽象:反应器引擎经此获取当前时刻
Functions§
- chain_
step - 计算单步链哈希:chain_hash = blake3(prev_hash + content_hash)
- compute_
chain_ hash - 计算哈希链的最终链哈希
- content_
hash - 计算内容的 BLAKE3 哈希
- fact_
hash - 计算 Fact 的哈希(基于稳定的 JSON 序列化)
- fact_
to_ stable_ json - 将 Fact 序列化为稳定的 JSON 格式
- local_
broadcaster - 创建单线程 event 广播通道(broadcast 语义:新订阅者不收历史)
- local_
pair - 创建单线程 command 通道对(unbounded mpsc 语义)
Type Aliases§
- Caller
Role Resolver - caller_role 解析器接缝(B-3)
- Event
Receiver - event 通道接收器(可克隆,用户/治理层 I/O 订阅者/审计器各自持有)
- Event
Sender - event 通道发送器(可克隆,反应器持有;通过
subscribe()创建新接收者) - Fact
Receiver - command 通道接收器(唯一,由反应器持有)
- Fact
Sender - command 通道发送器(可克隆,用于多个组件共享)
- IoResult
- I/O 执行结果