MoonLeaseKit

面向 MoonBit 的确定性租约、围栏令牌与领导者选举基础库。

Mooncakes：https://mooncakes.io/docs/dxh8888/moonleasekit

MoonLeaseKit 用纯 MoonBit 状态机描述分布式资源所有权。调用方显式传入逻辑时间，库不读取系统时钟，也不绑定数据库、网络、线程或服务发现组件，因此同一输入可以在 JavaScript、WebAssembly、WebAssembly-GC 和 Native 后端得到一致结果。

为什么需要围栏令牌

租约过期并不意味着旧持有者立即停止运行。网络分区、长时间 GC 或进程暂停都可能让旧持有者在恢复后继续写入。MoonLeaseKit 为每次新租约签发严格递增的 fencing token，存储侧只接受不低于已见最高令牌的写入，从而确定性拒绝迟到的旧持有者。

核心能力

获取、续约、释放、过期清理和原子移交租约；
单调 fencing token、版本前置条件和持有者身份校验；
多资源 LeaseTable、批量命令和完整审计事件；
存储侧 FenceGuard，拒绝旧令牌和令牌持有者冲突；
确定性候选排序、严格多数计算和 quorum certificate；
重复投票去重与同一任期双重投票检测；
外部持久化状态恢复前的安全不变量校验；
稳定 JSON、CLI、50,000 轮故障切换基准和轨迹审计；
核心逻辑零第三方依赖、零平台 API。

快速开始

moon add dxh8888/moonleasekit@0.1.0

moon check --target all
moon test --target wasm
moon test --target wasm-gc
moon test --target js
moon run cmd/main --target js
moon run bench/main --target js

CLI 会演示三节点投票、领导者租约签发、领导权移交，以及旧领导者携带旧令牌写入时被拒绝。

leader={"resource":"orders/leader","holder":"worker-a","token":1,...}
next_leader={"resource":"orders/leader","holder":"worker-b","token":2,...}
stale_write=false:stale fencing token rejected
audit={"valid":true,"checked_events":2,"findings":[]}

最小示例

let acquired = @moonleasekit.LeaseState::new("jobs/leader").apply(
  Acquire("worker-a", 10, None),
  100,
)

guard acquired.lease is Some(lease) else { return }

let write = lease.fenced_write("commit-job-42", 101).unwrap()
let checked = @moonleasekit.FenceGuard::new().check(write)
assert_true(checked.accepted)

时间值是调用方定义的单调逻辑 tick。生产系统可以映射到单调时钟、数据库版本或共识日志位置，但不应直接依赖可能回拨的墙上时钟。

基准证据

当前固定工作负载执行 50,000 次租约过期与接管：

cycles=50000
leases_acquired=50000
writes_accepted=50000
stale_writes_rejected=49999
final_token=50000
audit_valid=true
evidence=558449

evidence 是跨后端可复现的结果摘要，不代表运行耗时。性能测试计划见 docs/BENCHMARK_PLAN.md。

文档

项目边界

MoonLeaseKit 提供可嵌入的确定性协调原语，不实现网络通信、持久化驱动、故障检测器或完整共识协议。quorum certificate 只能证明输入投票达到指定多数，调用方仍需通过可信传输和持久化保证投票真实性与任期唯一性。

License

Apache-2.0。