# 0.8 Breaking Plan

更新时间：2026-04-24

本文档记录 `orion-error 0.8` 如果进入“不再兼容旧版本路径”的窗口，需要完成的收口工作。

目标不是现在立刻执行，而是把已经确认的 breaking 候选项、依赖原因和实施顺序固定下来，避免后续再次靠聊天记录回忆。

## 1. 当前已知不能直接删除、但属于兼容残留的 root 入口

以下名字目前仍保留在 crate root，原因不是“推荐主路径”，而是 derive 宏、示例或兼容导入仍依赖它们：

- `DomainReason`
- `ErrorConv`
- `ErrorCategory`
- `ErrorCode`
- `ErrorIdentityProvider`
- `ErrorRenderer`
- `RenderMode`
- `TextDiagnosticRenderer`
- `TextReportRenderer`
- `UvsFrom`
- `Visibility`

其中优先级最高的两个兼容残留是：

- `DomainReason`
  当前 `OrionError` derive 宏展开仍依赖 `orion_error::DomainReason`
- `ErrorConv`
  当前 `examples/order_case.rs` 仍使用 root `ErrorConv`

## 2. 0.8 应完成的 API 收口

### 2.1 去掉 derive 宏对 root `DomainReason` 的依赖

需要做的事：

- 修改 `orion_error_derive`，使宏展开不再要求 `orion_error::DomainReason`
- 优先改成显式引用稳定路径：
  - `orion_error::core::DomainReason`，或
  - `orion_error::reason` 下正式承诺的新路径
- 为 derive 行为补测试，锁住“不依赖 root `DomainReason` 也能展开”

完成后可以删除：

- root hidden `DomainReason`

### 2.2 去掉 root `ErrorConv` 的兼容入口

需要做的事：

- 修改 `examples/order_case.rs` 与相关文档
- 统一使用：
  - `orion_error::conversion::ErrorConv`，或
  - `orion_error::traits_ext::ErrorConv`

建议优先选 `conversion::ErrorConv`，保持主路径更集中。

完成后可以删除：

- root hidden `ErrorConv`

### 2.3 评估其余 root hidden 兼容入口是否整体移除

在 `DomainReason` / `ErrorConv` 收口后，下面这批应重新评估是否还保留 root hidden 兼容：

- `ErrorCategory`
- `ErrorCode`
- `ErrorIdentityProvider`
- `ErrorRenderer`
- `RenderMode`
- `TextDiagnosticRenderer`
- `TextReportRenderer`
- `UvsFrom`
- `Visibility`

建议原则：

- 如果某个名字仍承担 derive 入口职责，就保留
- 如果只是“历史上放在 root 也能用”，则迁回分层模块

当前判断：

- `ErrorCode`
- `ErrorIdentityProvider`

大概率仍应保留，因为它们同时承担 derive 名字入口。

## 3. 0.8 应完成的 compat API 移除

以下接口在 `0.7.x` 已明确属于 compat / deprecated 路径，`0.8` 应进入正式移除评估：

- `compat_prelude::*`
- `compat_traits::*`
- `ErrorOwe*` / `owe(...)`
- `ErrorWrap::err_wrap(...)`
- `WrapStructError::wrap(...)`
- `want(...)`
- `with_want(...)`
- `with(...)`
- `with_source(...)`
- `StructErrorBuilder::source(...)`

这里的原则应明确：

- 新代码主路径只讲 `doing(...)`
- `want(...)` / `with_want(...)` 只在兼容和迁移语境中存在

需要做的事：

- 检查所有示例、测试、README、教程是否还使用这些入口
- 把 remaining usage 全部迁到主路径：
  - `into_as(...)`
  - `wrap_as(...)`
  - `with_context(...)`
  - `doing(...)`
  - `at(...)`
  - `with_std_source(...)`
  - `with_struct_source(...)`
  - `source_std(...)`
  - `source_struct(...)`

## 4. 0.8 应完成的模块边界收口

### 4.1 重新评估 `advanced_prelude`

当前定位已经收敛为：

- 协议/schema 测试
- 迁移验证
- 大范围编译覆盖

0.8 应决定它是：

- 继续保留，但明确是测试/迁移工具箱
- 继续瘦身
- 或拆成更小的专用模块

### 4.2 重新评估 `types`

`types::*` 当前已经缩小，但仍有再次膨胀成“第二个 root”的风险。

0.8 应决定：

- 是否继续保留 `types`
- 若保留，只允许跨层共享 carrier
- 明确禁止重复导出 `report / runtime / bridge` 的主入口

## 5. 0.8 应完成的文档收口

需要同步更新：

- `README.md`
- `docs/README.md`
- `docs/tutorial.md`
- `docs/protocol-contract.md`
- `docs/stable-snapshot-schema.md`

需要明确写清：

- 哪些 root 名字是长期保留的正式入口
- 哪些 root 名字只是 derive 例外
- 哪些 compat 路径已被移除
- `advanced_prelude` / `types` 的最终定位

## 6. 建议执行顺序

推荐按下面顺序推进：

1. 先改 derive 宏，去掉对 root `DomainReason` 的依赖
2. 再迁移 example / docs，去掉 root `ErrorConv`
3. 然后收 root hidden export
4. 再移除 compat API
5. 最后更新 README / tutorial / docs 索引

## 7. 当前结论

到 `0.7.x` 当前状态为止，可以确定：

- root hidden export 已经收窄到较小集合
- 大部分历史 hidden alias 已经删掉
- `DomainReason` 与 `ErrorConv` 是当前仍未完成收口的两个关键兼容点

因此，`0.8` 的 breaking 工作重点，不再是继续零碎删 API，而是：

- 去掉 derive / example 对 root 兼容入口的依赖
- 然后一次性正式收口 root 与 compat 表面
