Skip to main content

Crate evorule_reactor

Crate evorule_reactor 

Source
Expand description

EvoRule 反应式执行器

§设计原则

  • 事实驱动:所有交互通过 Fact 通道进行
  • 单一串行通道:保证调度确定性
  • 稳定检测:队列空 + 无待处理 I/O = 稳定
  • 无状态泄漏:所有状态由反应器维护
  • Append-Only 审计链:所有 Fact 追加到 FactsLog,支持审计重放

§架构

用户/治理层 → FactSender → [command mpsc] → 反应器
                                               ↓
                                         调用 TCB 核心
                                               ↓
                                 产生新 Fact → event broadcast → 用户/I/O 订阅者/审计器
                                               ↓
                                 所有 Fact → FactsLog(审计链)

§模块结构

  • fact — Fact 枚举、FactId、IoType
  • io_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§

ChannelPair
双通道对(command mpsc + event broadcast)
ClockHandle
时钟句柄:引擎持有的 RuntimeClock 共享指针
FactId
事实唯一标识符
FactIdGenerator
事实 ID 生成器(单调递增)
FactsLog
Append-Only 事实审计链
FixedClock
固定时钟(测试与确定性验证用)
HashError
哈希计算错误类型
InvariantScanReport
最近一轮不变式扫描报告(每迭代头随内置自检刷新)
IoCallContext
I/O 调用上下文 —— 权限判定与审计对齐的信息载体
IoDispatcher
I/O 分发器(机制层)
IoDispatcherBuilder
I/O 分发器 builder(链式注册)
IoType
I/O 请求类型(与 core_eval.json 中的 io_type 对应)
LocalEventReceiver
单线程 event 接收端(每订阅者独立队列)
LocalEventSender
单线程 event 发送端(broadcast 语义:多订阅者、各自独立队列、新订阅者不收历史)
LocalReceiver
单线程 command 接收端(单消费者 FIFO)
LocalSender
单线程 command 发送端(unbounded mpsc 语义,可克隆共享同一队列)
PendingIoEntry
阶段6:pending I/O 详情条目(snapshot 中单个 I/O 请求的状态)
PhaseContext
阶段转移上下文(纯数据,用于转移函数判断)
Reactor
反应器实例
ReactorBuilder
反应器配置构建器
ReactorHandle
反应器任务句柄
ReactorStateSnapshot
反应器状态快照(只读访问,供 tier2 查询)
StableDetector
稳定检测器
SystemClock
系统时钟(native 默认后端)
TraceHit
单条规则命中归因的 trace 条目

Enums§

CallerRole
调用者角色 —— 调用时“代表谁“(区别于规则 author:author 表示“谁写的“)
ControlFlowType
控制流指令类型(G8 合规:唯一真值来源,位于 fact.rs 受豁免)
Fact
事实(Fact)—— 系统的原子通信单元
FactsLogError
FactsLog 错误类型
InvariantViolation
不变式违规
ReactorError
反应器错误
ReactorPhase
反应器执行阶段

Traits§

IoHandler
I/O Handler trait —— 所有 I/O handler 实现此接口
RuntimeClock
时钟抽象:反应器引擎经此获取当前时刻

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§

CallerRoleResolver
caller_role 解析器接缝(B-3)
EventReceiver
event 通道接收器(可克隆,用户/治理层 I/O 订阅者/审计器各自持有)
EventSender
event 通道发送器(可克隆,反应器持有;通过 subscribe() 创建新接收者)
FactReceiver
command 通道接收器(唯一,由反应器持有)
FactSender
command 通道发送器(可克隆,用于多个组件共享)
IoResult
I/O 执行结果