Consistency And Idempotency

一致性模型

• 资源写入采用读写一致的控制面语义。
• 运行输出采用“事实先落库、读模型异步投影”的最终一致模型。
• UI 与 webhook 面向读模型和事件 replay，而不是面向进程内缓存。

幂等原则

• 创建 run 的命令 SHOULD 支持 idempotencyKey
• cancel、notify、fail 等命令 MUST 具备幂等语义
• runtime 发布输出事件时，平台 MUST 能基于 (runId, eventId) 或 (runId, sequence) 去重
• webhook 投递为至少一次，消费者 MUST 使用 eventId 去重
• trace span 导出 SHOULD 至少基于 (traceId, spanId) 去重
• trace event 导出 SHOULD 至少基于 (traceId, spanId, eventId) 或稳定事件指纹去重

排序原则

• run 内输出事件顺序以 sequence 为准
• thread 内的展示顺序 MUST 可由 sequence 和 sortAt 稳定推导
• 同一 run 内不同消费者看到的 terminal event 顺序 MUST 一致
• 同一 trace 内 span 的父子关系 MUST 通过 traceId、spanId、parentSpanId、rootSpanId 稳定重建
• 同一 span 内 TraceEvent 的展示顺序 SHOULD 通过 timestamp 与稳定 tie-break key 重建

Projection 原则

• projection MUST 是可重建的
• projection MUST NOT 依赖单实例内存作为唯一状态
• projection MAY 使用 lease、cursor 和 buffer，但这些只是优化，不是事实源

失败语义

• provider 失败、runtime 断连、webhook 失败、projection 延迟均 MUST 被记录为事件或可审计状态
• 运行事实与读模型偏差时，以事件流为准并触发重建
• tracing 属于辅助遥测平面；trace 记录缺失 MUST NOT 改变 run 状态，但 SHOULD 触发观测告警
• GenAI 内容详情如果因策略或大小原因未捕获，MUST 在读面上可区分为“未捕获”而不是静默缺失