#mooncmd

#特性

• 纯事件主链：命令处理器为纯函数 (S, C) -> Result[Array[E], CommandError]，只做业务裁决、不碰元数据与 存储；AggregateRoot 承担生命周期（执行 / 提交 / 重放重建 / 快照）。
• 元数据自动包装：EventMessage 由框架独占组装——event_id（UUID v4）、 correlation_id 承自命令、causation_id 记前因、user_id 全链透传、 schema_version 预留位、时间戳唯一取自 @async.now() 注入点。
• 乐观并发：批次首事件版本必须等于当前版本 + 1，否则 DuplicateVersion 拒写；表级 UNIQUE(aggregate_id, version) 竞态兜底； 事务失败整体回滚。
• 快照加速：to_snapshot / SnapshotStore 记录面 + from_snapshot 基态重建（快照读路径已接入分发主流程）；快照态起跑 + 尾部重放与全量 重放等价有契约钉。
• 拉取式投影：Projection 记录面 + LiveProjection（订阅位置 Origin / Current / FromVersion，检查点即版本）+ SQLite 持久化投影。
• Effect 重试状态机：RetryMachine 协议面（错误分类封闭集 + 纯裁决， 无时钟无副作用）+ exec_with_effect（固定 / 指数退避、按错误类别 分派、熔断；退避等待由调用方注入）。
• 聚合词表代码生成：TOML 声明（约 30–50 行）自动产出状态结构、事件与 命令枚举、apply 演化链、命令分派骨架、wire 序列化与契约测试门； 业务裁决归手写策略钩子。
• Monad 注入面：monads 子包提供 State / Writer / Reader / EventWriter 纯函数基础设施，不含事件溯源语义。

#安装

moon add thy1016/mooncmd

import {
  "thy1016/mooncmd/aggregate",
  "thy1016/mooncmd/command",
  "thy1016/mooncmd/event",
  "thy1016/mooncmd/store",
}

#快速上手

#定义聚合并执行命令

let root = @aggregate.AggregateRoot::new(
  "account-001",
  account_handler,                                   // (S, C) -> Result[Array[E], CommandError]
  @event.EventApplier::Single(account_applier),      // (S, E) -> S
  AccountState::init(),
)
let root = root.exec(AccountCommand::CreateAccount("Demo", 1000))
let root = root.exec(AccountCommand::DepositMoney(500))

#SQLite 落库与重放重建

let store = @store.SQLiteEventStore::new(
  "ledger.db", account_serialize, account_deserialize, account_type_name,
)
store.append("account-001", root.uncommitted_events())
let rebuilt = @aggregate.AggregateRoot::from_events(
  "account-001", store.load("account-001", 0),
  account_handler, @event.EventApplier::Single(account_applier),
  AccountState::init(),
)

#统一分发（dispatch 门面）

let committed = @mooncmd.dispatch(
  records,                                  // EventStore 记录面
  None,                                     // EventBus（可选）
  root,                                     // 聚合根
  AccountCommand::DepositMoney(500),        // 命令
  projections=[live_projection],            // Strong 模式需等待的投影
  consistency=@mooncmd.Strong,              // 默认 Eventual
)

#Effect 重试（乐观并发自动重试）

let machine : @aggregate.RetryMachine = {
  default_action: fn(kind) {
    match kind {
      @aggregate.Duplicate => @aggregate.ActionRetry   // 并发冲突：重放重执行
      _ => @aggregate.ActionExhausted                  // 业务拒：重放同结果，不重试
    }
  },
  decide: fn(attempt, _failures, _kind) {
    if attempt > 3 {
      @aggregate.GiveUpRaise
    } else {
      @aggregate.WaitRetry(wait_ms=100L)
    }
  },
}
let root = root.exec_with_effect(
  AccountCommand::DepositMoney(500), machine,
  @aggregate.RetryHooks::none(), fn(ms) { /* 退避等待，由调用方注入 */ },
)

#聚合词表代码生成

[aggregate.state]
fields = [{ name = "balance", type = "int", init = "0" }]

[[aggregate.events]]
name = "MoneyDeposited"
fields = [{ name = "amount", type = "int" }]
evolve = ["add balance=amount"]

moon test                           # 生成产物结构钉 + 契约测试 + 已知答案校验

#API 总览

#错误面

#设计边界

• 命令处理器只返回纯事件；事件元数据由 AggregateRoot 独占包装； 持久化只经 Router 触发。
• 事件时间戳只来自 @async.now() 注入点；投影与确定性路径不读取 当前时钟。
• 不做分布式 / 跨进程事件总线（EventBus 仅进程内可选挂点）；不做 事件升级 / 迁移框架（schema_version 只预留）；不承诺第二存储后端； 不内置业务聚合（examples/bank 为示例与测试模板）。

#测试与验证

moon test --target native               # 全模块测试（wasm 同支持）
moon run examples/bank --target native  # 全链自证，终行 EXAMPLE:PASS

#许可证