nasaga-core

nasaga-core 是无 I/O 的 Saga 合同层，负责流程定义、稳定身份、结果分类、封闭状态机和冻结补偿计划。业务应用通常通过 nasa 门面的 saga feature 使用；只有自定义运行时或持久化适配器需要直接依赖本 crate。

它解决的是分布式业务流程的确定性裁决：重投不会换一个业务效果身份，定义升级不会用新流程解释旧实例，结果未知不会被当成失败直接补偿，补偿计划也不会在运行中被迟到事件改写。该层不访问数据库或消息系统，因此 Orchestrator、参与方和自定义 adapter 可以复用同一份状态与身份合同。

SagaPayload 保存原始业务字节、content_type 与 schema_id；步骤通过 SagaPayloadContract 声明精确合同。默认合同是无 schema 的 JSON；非 JSON 字节无需转成 JSON，schema 标识也不会被忽略。合同参与 definition 摘要，运行时验证首步输入与参与方声明一致，业务负责按声明解析字节。

合同架构

WorkflowDefinition + definition digest
                  │
                  ├─ stable identity: saga / business / effect / command
                  ├─ typed outcome: success / reject / unknown
                  └─ closed transition: forward → cancel/resolve → compensate/manual
                                                   │
                                                   └─ frozen compensation plan

定义、身份和状态迁移都是普通值；I/O、事务、重投、租约与进程生命周期分别由 nasaga-mysql、nasaga-runtime 和 napp 承担。

[dependencies]
nasa = { version = "2.0.6", features = ["saga"] }

定义流程

use std::time::Duration;
use nasa::saga::{
    CancelMode, Compensation, DefinitionVersion, ResolutionMode, ResolutionSpec,
    ServiceIdentity, StepDefinition, StepName, TimeoutPolicy, WorkflowDefinition, WorkflowName,
};

let payment = StepDefinition::new(
    StepName::new("capture_payment")?,
    ServiceIdentity::new("payment-service")?,
    Compensation::NonCompensable,
    CancelMode::ResolveOnly,
    ResolutionSpec::allowed(ResolutionMode::Poll, Duration::from_secs(120)),
    Duration::from_secs(15),
    TimeoutPolicy::AcceptLateSuccess,
);

let definition = WorkflowDefinition::new(
    WorkflowName::new("checkout")?,
    DefinitionVersion::new(1)?,
    vec![payment],
)?;
# Ok::<(), Box<dyn std::error::Error>>(())

流程定义发布后，同一 definition_version 对应的步骤、owner、取消策略、裁决预算和顺序必须保持不变。任何语义变化都使用新的定义版本，运行中实例始终按创建时绑定的摘要恢复和补偿。

身份语义

saga_id 标识一次流程实例，business_key 负责业务创建幂等。
effect_id 标识当前阶段的业务效果，跨投递尝试保持稳定。
command_id 标识单次投递，不能替代业务效果身份。
取消与裁决通过 target_phase() 和 target_effect_id() 指向原始操作，不能使用当前控制命令的身份查询外部事实。

YML 配置

本 crate 不读取 yml。流程定义应来自受信、不可变的应用配置或控制面快照，并在进程进入 Ready 前注册到运行时。

主要边界

LocalFenceable 不允许产生 Unknown 结果。
ResolveOnly 必须声明有界裁决策略；当前运行时支持 Poll。
不可补偿的 pivot 只能位于流程末端，避免补偿计划包含无法撤销的已成功步骤。
Saga 提供本地事务、可靠消息和补偿组成的最终一致性，不提供跨服务 ACID 或并发隔离。
资源竞争仍需由业务唯一键、条件更新、语义锁或可交换操作保护。