协议契约

更新时间：2026-04-23

本文档描述 orion-error 当前已经落地的协议层设计。

这里说的“协议层”不是新的 runtime 传播模型，而是对外稳定消费接口。

1. 三层结构

当前协议层由三层组成：

1. 稳定身份：ErrorIdentity
2. exposure 决策：ExposureDecision
3. 出口投影：HTTP / CLI / log / RPC / user debug

推荐把它理解为：

• StructError<R> 负责运行时传播
• ErrorIdentity 负责稳定识别
• DiagnosticReport 负责人类诊断
• ErrorProtocolSnapshot 负责把 identity + decision + report 组装成统一消费输入

2. 稳定身份

稳定身份结构是 ErrorIdentity。

字段：

• code
• category
• reason
• detail
• position
• path

语义：

• code：稳定机器主键
• category：稳定分类
• reason：稳定的人类摘要
• detail：可变补充说明，不是主键
• path：稳定导出的路径投影
• 当前 runtime 主语义仍应优先理解为 action / locator / path segments

入口：

• StructError::identity_snapshot()
• assert_err_code(...)
• assert_err_category(...)
• assert_err_identity(...)

注意：当前 assert_err_code(...) 断言的是 stable code 字符串，不是数值 error_code()。

3. Exposure

exposure 决策结构是 protocol::ExposureDecision。

字段：

• http_status
• visibility
• default_hints
• retryable

默认 exposure 策略实现是 protocol::DefaultExposurePolicy。

当前默认规则：

• Biz -> 400 + Public
• Conf / Logic / Sys -> 500 + Internal
• sys.network_error / sys.timeout -> retryable = true
• 其他 stable code 默认 retryable = false

说明：

• 当前文档中的运行时主路径仍然是 doing(...)
• top-level want 已从 identity / snapshot / protocol 投影中移除
• 兼容残留主要收在 context frame 的 target

主要入口：

• ExposurePolicy::decide(...)
• StructError::exposure(...)
• StructError::into_exposure(...)
• 完整 projection 数据以 StructError::exposure(...) 为主路径

4. ErrorProtocolSnapshot

ErrorProtocolSnapshot 是当前统一协议输入。

结构：

• identity
• decision
• 内嵌诊断 report，可通过 report() 只读访问

入口：

• StructError::exposure(...)
• StructError::into_exposure(...)

适用场景：

• 测试快照
• 网关二次投影
• 协议统一出口
• 用户调试摘要

5. HTTP Projection

JSON 字段：

• status
• code
• category
• message
• visibility
• hints

规则：

• Public 时，message 优先使用 detail
• Internal 时，message 使用稳定 reason

入口（需要 serde_json feature）：

• ErrorProtocolSnapshot::to_http_error_json()

6. CLI Projection

JSON 字段：

• code
• category
• summary
• detail
• visibility
• hints

规则：

• summary 使用 compact render
• detail 使用 verbose render

入口（需要 serde_json feature）：

• ErrorProtocolSnapshot::to_cli_error_json()

7. Log Projection

JSON 字段：

• code
• category
• reason
• detail
• operation
• path
• visibility
• hints
• root_metadata
• context
• source_frames

规则：

• 保留完整 context
• 保留 root_metadata
• 保留 source_frames

入口（需要 serde_json feature）：

• ErrorProtocolSnapshot::to_log_error_json()

8. RPC Projection

JSON 字段：

• status
• code
• category
• reason
• detail
• visibility
• hints
• retryable

规则：

• detail 只在 Public 可见时保留
• retryable 完全来自 exposure decision

入口（需要 serde_json feature）：

• ErrorProtocolSnapshot::to_rpc_error_json()

9. User Debug Summary

render_user_debug(...) 是给人看的调试摘要，不是机器协议。

入口：

• ErrorProtocolSnapshot::render_user_debug()
• ErrorProtocolSnapshot::render_user_debug_redacted(...)

它的定位是：

• 本地调试
• 示例输出
• 人工排障

它不是：

• public HTTP message
• 稳定 JSON schema

10. DiagnosticReport

DiagnosticReport 是 report 层对象。

它不依赖 ErrorIdentityProvider，因此更适合：

• 文本渲染
• redaction
• 人类诊断

常用入口：

• StructError::report()
• StructError::into_report()
• StructError::report() / into_report()

如果启用了 serde_json feature，还可以使用：

• 协议投影应改走 StructError::exposure(...)
• 然后使用 ErrorProtocolSnapshot::to_*_json()

11. 建议的消费路径

推荐顺序：

1. 运行时传播用 StructError<R>
2. 要稳定识别时取 identity_snapshot()
3. 要统一出口规则时取 exposure(...)
4. 要协议出口时使用 projection API
5. 要人类摘要时使用 render_user_debug(...)

不建议：

• 直接把 Display 文本当协议主键
• 直接把 CLI 文本当机器协议
• 用 detail 全文本做唯一稳定断言