Struct ParticipantRuntime 

pub struct ParticipantRuntime<B: SagaBackend> { /* private fields */ }

业务作用：参与方运行时——持有 store/inbox/outbox 句柄与本服务的 Inbox consumer 名。

无进程内业务状态；并发安全由 gate 行锁与 Inbox 唯一键承担。

Implementations

impl<B> ParticipantRuntime<B>

where B: SagaBackend + SagaBackendFactory,

pub fn new( consumer: impl Into<String>, command_trust: impl IntoIterator<Item = ParticipantCommandTrust>, ) -> Result<Self>

业务作用：构造参与方运行时。

参数说明：

• consumer: 本服务的小写 canonical Inbox consumer 名称（各服务唯一，去重命名空间）。
• command_trust: 从受信 definition/deployment 投影得到的精确 Orchestrator 授权边。

返回：consumer 满足 128 字节小写 canonical Inbox key 时返回不建连的运行时； 非法去重命名空间或空信任投影返回错误，避免未认证 command 获得业务入口。

pub fn with_datasource( consumer: impl Into<String>, command_trust: impl IntoIterator<Item = ParticipantCommandTrust>, datasource: impl AsRef<str>, ) -> Result<Self>

业务作用：构造绑定命名 datasource 的参与方运行时。

参数说明：

• consumer: 本服务的 canonical Inbox consumer 名称。
• command_trust: 从受信 definition/deployment 投影得到的 Orchestrator 授权边。
• datasource: Inbox、gate、业务事实与 result Outbox 共享的数据源。

返回：身份、信任投影与 datasource 合法时返回同源 runtime；任一边界不成立时在 I/O 前拒绝。

pub fn build( consumer: impl Into<String>, command_trust: impl IntoIterator<Item = ParticipantCommandTrust>, backend: B, ) -> Result<Self>

业务作用：把已验证的参与方配置与完整后端组合为唯一运行句柄。

参数说明：consumer 是 Inbox 去重命名空间，command_trust 是授权投影，backend 绑定同源持久角色。

返回：边界均合法时返回运行时；任一身份或投影冲突时在 I/O 前拒绝。

pub fn datasource_ref(&self) -> &DatasourceRef

业务作用：读取参与方原子处理链绑定的 datasource 身份。

参数说明: 无。

返回：Inbox、Saga gate 与 Outbox 共用的不可变 qualifier。

pub fn authenticate<'a>( &'a self, producer: &'a ServiceIdentity, ) -> Result<AuthenticatedParticipantRuntime<'a, B>>

业务作用：把 transport 已认证 producer 收窄成只能调用 authenticated phase API 的能力视图。

参数说明：

• producer: transport 从 mTLS/SASL principal、独占 topic 或签名 key 映射出的身份。

返回：身份至少拥有一条启动投影时返回能力视图；否则在解析 envelope 与接触数据库前拒绝； 每个 phase 仍会按该 envelope 的 workflow/version/digest 再做精确授权。

pub fn single_trusted_command_producer(&self) -> Result<ServiceIdentity>

业务作用：读取单一受信 command producer，供 Application 自动装配单参与方 transport 身份绑定。

该入口只在全部 workflow projection 都归属于同一逻辑 Orchestrator 时成立；多 producer 参与方 必须由业务显式选择当前 listener principal 对应的 producer，不能由容器猜测授权边。

参数说明: 无。

返回：恰有一个受信 producer 时返回其稳定逻辑身份；存在多个 producer 时返回配置错误。

pub fn verify_authenticated_command( &self, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, ) -> Result<()>

业务作用：为自定义 connector 预检 command envelope 与 producer 的精确授权投影。

该预检不替代 phase handler 内的强制复验；它用于在解析业务 payload、获取连接或触碰 Inbox 之前给 HTTP/gRPC adapter 一个统一的 fail-closed 入口。

参数说明：

• envelope: transport 已校验完整性、但尚未获业务授权的原始 command envelope。
• producer: transport 从签名、mTLS 或独占 route 映射出的逻辑 Orchestrator。

返回：身份派生与 workflow/version/digest/producer 投影全部匹配时成功；否则类型化拒绝。

pub async fn handle_authenticated_execute<S>( &self, service: &S, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, allow_unknown: bool, ) -> Result<ParticipantHandled>

where S: SagaStep, S::Command: DeserializeOwned,

业务作用：execute 命令的完整本地事务 wrapper——gate 准入、业务执行、结果发布。

参数说明：

• service: 业务步骤实现。
• envelope: 已通过 transport 层 producer 认证的命令 envelope。
• producer: transport 认证并映射出的 Orchestrator 逻辑身份。
• allow_unknown: descriptor 声明的 allow_unknown；纯本地步骤返回 Unknown 会按合同违规提交 Halted（不能进入无界等待）。

返回：可 ACK 的处理结论（COMMIT 已确认）；Retryable、身份复验失败或基础设施 失败返回错误（已回滚，不得 ACK）。

pub async fn handle_authenticated_execute_traced<S>( &self, service: &S, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, receipt_trace: Option<&TraceContext>, allow_unknown: bool, ) -> Result<ParticipantHandled>

where S: SagaStep, S::Command: DeserializeOwned,

业务作用：携带命令收据链路上下文的 execute 事务 wrapper——结果事件由收据派生 子上下文，保持参与方到编排端的 trace 连续。

参数说明：

• service: 业务步骤实现。
• envelope: 已通过 transport 层 producer 认证的命令 envelope。
• producer: transport 认证并映射出的 Orchestrator 逻辑身份。
• receipt_trace: transport 收据显式解析出的链路上下文；None 表示未携带。
• allow_unknown: descriptor 声明的 allow_unknown。

返回：语义与 handle_authenticated_execute 完全一致；trace 不改变事务序与可 ACK 边界。

pub async fn handle_authenticated_cancel_local( &self, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, ) -> Result<ParticipantHandled>

业务作用：local_fenceable 步骤的取消命令 wrapper——在 gate 行锁上完成取消屏障裁决。

参数说明：

• envelope: 已认证的取消命令 envelope。
• producer: transport 认证并映射出的 Orchestrator 逻辑身份。

返回：可 ACK 的裁决结论（Confirmed/AlreadyTerminal/ResolutionPending 之一已 连同结果事件提交）；基础设施失败返回错误（已回滚，不得 ACK）。

pub async fn handle_authenticated_cancel_local_traced( &self, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, receipt_trace: Option<&TraceContext>, ) -> Result<ParticipantHandled>

业务作用：携带命令收据链路上下文的本地可围栏取消事务 wrapper；结果事件由收据 派生子上下文，语义与 handle_authenticated_cancel_local 一致。

参数说明：

• envelope: 已通过 transport owner/route 认证的 cancel command。
• producer: transport 认证并映射出的 Orchestrator 逻辑身份。
• receipt_trace: transport 收据显式解析出的链路上下文；None 表示未携带。

返回：真实裁决与结果事件 COMMIT 后返回可 ACK 结论；失败返回错误并回滚。

pub async fn handle_authenticated_cancel_external<C>( &self, service: &C, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, ) -> Result<ParticipantHandled>

where C: SagaCancelStep, C::Command: DeserializeOwned,

业务作用：externally-cancellable 步骤的类型化取消事务 wrapper。

固定顺序为 Inbox claim → gate 行锁/取消准入 → 外部 cancel handler → 真实裁决落账 → result Outbox → COMMIT。handler 调用期间 gate 权威持续持有，使并发 execute 不可能越过 已确认取消；ResolutionPending 如实保留 Unknown，交 Poll resolver 收敛。

参数说明：

• service: 同时托管步骤取消能力的业务 Service。
• envelope: 已通过 transport owner/route 认证的 cancel command。
• producer: transport 认证并映射出的 Orchestrator 逻辑身份。

返回：真实裁决与结果事件 COMMIT 后返回可 ACK 结论；Retryable、payload 合同、失权 或基础设施失败返回错误并回滚，transport 不得 ACK。

pub async fn handle_authenticated_cancel_external_traced<C>( &self, service: &C, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, receipt_trace: Option<&TraceContext>, ) -> Result<ParticipantHandled>

where C: SagaCancelStep, C::Command: DeserializeOwned,

业务作用：携带命令收据链路上下文的外部取消事务 wrapper；结果事件由收据派生 子上下文，语义与 handle_authenticated_cancel_external 一致。

参数说明：

• service: 同时托管步骤取消能力的业务 Service。
• envelope: 已通过 transport owner/route 认证的 cancel command。
• producer: transport 认证并映射出的 Orchestrator 逻辑身份。
• receipt_trace: transport 收据显式解析出的链路上下文；None 表示未携带。

返回：真实裁决与结果事件 COMMIT 后返回可 ACK 结论；失败返回错误并回滚。

pub async fn handle_authenticated_compensate<S>( &self, service: &S, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, ) -> Result<ParticipantHandled>

where S: SagaStep, S::Compensation: DeserializeOwned,

业务作用：补偿命令的完整本地事务 wrapper——按 effect_id 幂等撤销正向效果。

参数说明：

• service: 业务步骤实现。
• envelope: 已认证的补偿命令 envelope。
• producer: transport 认证并映射出的 Orchestrator 逻辑身份。

返回：可 ACK 的处理结论；补偿已成功时按幂等成功重发结果；本地无正向成功效果 时提交 Halted 合同违规事实（ParticipantHandled::ContractViolation）； Retryable 或基础设施失败返回错误（已回滚，不得 ACK）。

pub async fn handle_authenticated_compensate_traced<S>( &self, service: &S, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, receipt_trace: Option<&TraceContext>, ) -> Result<ParticipantHandled>

where S: SagaStep, S::Compensation: DeserializeOwned,

业务作用：携带命令收据链路上下文的补偿事务 wrapper；结果事件由收据派生子上下文， 语义与 handle_authenticated_compensate 一致。

参数说明：

• service: 业务步骤实现。
• envelope: 已通过 transport owner/route 认证的 compensate command。
• producer: transport 认证并映射出的 Orchestrator 逻辑身份。
• receipt_trace: transport 收据显式解析出的链路上下文；None 表示未携带。

返回：补偿裁决与结果事件 COMMIT 后返回可 ACK 结论；失败返回错误并回滚。

pub async fn handle_authenticated_resolve<R>( &self, service: &R, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, ) -> Result<ParticipantHandled>

where R: SagaResolveStep, R::Command: DeserializeOwned,

业务作用：运行 poll 解决命令的类型化本地事务，把未知外部效果收敛为唯一裁决。

Inbox claim、gate 方向裁决、查询结论与结果 Outbox 在同一事务提交；Unknown 只保持 PENDING 供下一有界 attempt 继续查询，确定终态以后新 attempt 只能重放，避免重复调用 可能带 void/cancel-inquiry 副作用的裁决型接口。

参数说明：

• service: 实现 SagaResolveStep 的类型化查询服务。
• envelope: 已通过 transport producer 认证的 resolve 命令。
• producer: transport 认证并映射出的 Orchestrator 逻辑身份。

返回：事务提交后返回可 ACK 结论；Retryable、身份复验、方向合同或基础设施失败 返回错误并回滚，transport 不得 ACK。

pub async fn handle_authenticated_resolve_traced<R>( &self, service: &R, envelope: &SagaCommandEnvelope, producer: &ServiceIdentity, receipt_trace: Option<&TraceContext>, ) -> Result<ParticipantHandled>

where R: SagaResolveStep, R::Command: DeserializeOwned,

业务作用：携带命令收据链路上下文的解决查询事务 wrapper；结果事件由收据派生 子上下文，语义与 handle_authenticated_resolve 一致。

参数说明：

• service: 托管解决查询能力的业务 Service。
• envelope: 已通过 transport owner/route 认证的 resolve command。
• producer: transport 认证并映射出的 Orchestrator 逻辑身份。
• receipt_trace: transport 收据显式解析出的链路上下文；None 表示未携带。

返回：解决裁决与结果事件 COMMIT 后返回可 ACK 结论；失败返回错误并回滚。