@calcit/procs 0.12.19 → 0.12.20

package/rfc/02-14-project-modernization-roadmap.md

@@ -0,0 +1,229 @@
+# 项目现代化路线图（Rust 导向）
+
+## 为什么现在做
+
+当前架构已可用，但仍存在一些在现代 Rust 项目中通常会优先清理的可维护性热点：
+
+- `src/` 下模块边界较宽，部分职责混合了 runtime/codegen/CLI 关注点；
+- 仍有遗留/重复文件（例如：`src/calcit/struct.rs` 与 `src/calcit/calcit_struct.rs`）；
+- 生成产物流程依赖本地命令与脚本，尚未稳定地固化为 CI/任务体系；
+- 基准与验证流程主要靠“口口相传”的命令知识，不是项目内的一等资产。
+
+## 阶段 1：低风险整理（高 ROI）
+
+### 1）移除无效/重复模块
+
+- 候选：`src/calcit/struct.rs` 看起来是遗留文件，且未被 `src/calcit.rs` 接入。
+- 保留 `src/calcit/calcit_struct.rs` 作为唯一权威实现。
+
+预期收益：
+
+- 降低核心类型导航时的认知负担；
+- 降低“改到错误文件”的风险。
+
+### 2）统一模块命名约定
+
+当前风格混用了 `calcit_struct.rs` 与 `list.rs`/`tuple.rs` 这类通用命名。
+
+建议：
+
+- 在 `src/calcit/` 选择并坚持一种命名约定：
+  - 要么全部采用 `calcit_*.rs`；
+  - 要么全部采用类型语义命名，并由统一索引模块导出。
+
+预期收益：
+
+- `grep` 与跳转更直接；
+- 对新贡献者与工具链更一致友好。
+
+### 3）把高频检查提升为脚本/任务
+
+将关键验证收敛为显式脚本（或任务别名），并保证输出稳定：
+
+- 格式化/静态检查（`cargo fmt`、`cargo clippy -- -D warnings`）；
+- 编译/测试（`yarn compile`、`cargo test`、`yarn check-all`）；
+- 聚焦 JS 路径的 benchmark smoke test。
+
+预期收益：
+
+- 减少命令漂移；
+- 本地开发与 CI 更容易对齐。
+
+## 阶段 2：结构化整理（中等工作量）
+
+### 4）将 `src/codegen/emit_js.rs` 拆为内聚子模块
+
+`emit_js.rs` 体量较大，当前承载了多类职责：
+
+- 符号转义；
+- 参数/recur 模板决策；
+- import/tag 组织；
+- 表达式渲染。
+
+建议：
+
+- 按职责拆为子模块，例如：
+  - `emit_js/symbols.rs`
+  - `emit_js/functions.rs`
+  - `emit_js/imports.rs`
+  - `emit_js/tags.rs`
+
+预期收益：
+
+- 评审可读性更好；
+- 后续优化时回归风险更低。
+
+### 5）收敛 runtime helper 接口面
+
+随着 helper 持续增加（`_args_throw`、`_args_fewer_throw`、`_args_between_throw`、`init_tags`），建议在 TS runtime 内按能力分组并形成明确边界：
+
+- `arity helpers`；
+- `tag helpers`；
+- `list/map helpers` 等。
+
+预期收益：
+
+- JS codegen 演进更平滑；
+- API 兼容边界更清晰。
+
+## 阶段 3：现代 Rust 项目形态（较大工作量）
+
+### 6）评估 Cargo workspace 拆分
+
+可考虑的内部 crate：
+
+- `calcit-core`（数据模型 + 求值器）；
+- `calcit-codegen-js`；
+- `calcit-cli`。
+
+预期收益：
+
+- 编译影响域更小；
+- 对外/对内 API 边界更清楚；
+- 长期模块化能力更强。
+
+### 7）为热点路径引入 criterion 基准
+
+将以下基准固化为可重复执行资产：
+
+- tail recursion 模板路径；
+- tag 初始化开销；
+- rest 参数转换路径。
+
+预期收益：
+
+- 优化决策更客观；
+- 避免凭体感调优。
+
+## 建议执行顺序
+
+1. 先做 dead file 清理 + 命名规范收敛。
+2. 再做 JS codegen 文件拆分（仅重组，不改行为）。
+3. 引入 benchmark harness。
+4. 边界稳定后，再评估 workspace 拆分。
+
+## 执行追踪计划（用于持续跟踪）
+
+> 状态约定：`TODO` / `DOING` / `DONE`
+
+### Milestone A（稳健起步，低风险）
+
+- [x] `DONE` 把路线图转为中文并统一结构。
+- [x] `DONE` 清理 dead/重复模块（已移除：`src/calcit/struct.rs`）。
+- [x] `DONE` 在关键位置补测试（覆盖 JS codegen 新模板行为）：
+  - `tmpl_import_procs` 是否引入 `init_tags`；
+  - `tmpl_tags_init` 是否统一走 `init_tags(...)`；
+  - `tmpl_tail_recursion` 是否包含周期 watchdog 语义。
+- [x] `DONE` 跑针对性测试 + 全量回归（`cargo test -q snippets::tests` / `yarn check-all`）。
+- [x] `DONE` 将高频验证命令固化为脚本（`fmt-rs`/`lint-rs`/`test-rs`/`test-snippets`/`bench-recur-smoke`/`check-smooth`）。
+
+验收标准：
+
+- dead file 不再保留重复定义；
+- 新增测试能锁定关键模板行为，避免回归；
+- 所有验证命令通过。
+
+### Milestone B（结构化整理）
+
+- [ ] `DOING` 拆分 `emit_js.rs`（仅移动代码，不改变行为）。
+  - 已完成子任务：抽离 `tag_access` / `is_simple_tag_name` 到 `src/codegen/emit_js/tags.rs`，并补充对应单测。
+  - 已完成子任务：抽离 `escape_var` / `escape_cirru_str` 到 `src/codegen/emit_js/symbols.rs`，并补充对应单测。
+  - 已完成子任务：抽离 `to_js_import_name` / `to_mjs_filename` 到 `src/codegen/emit_js/paths.rs`，并补充对应单测。
+  - 已完成子任务：抽离 `get_proc_prefix` / `is_cirru_string` 到 `src/codegen/emit_js/runtime.rs`，并补充对应单测。
+  - 已完成子任务：抽离 `gen_args_code` 到 `src/codegen/emit_js/args.rs`，并补充普通参数/展开参数单测。
+  - 已完成子任务：抽离 `gen_call_args_with_temps` 及其内部判定 helper 到 `src/codegen/emit_js/args.rs`。
+  - 已完成子任务：抽离 `contains_symbol` / `sort_by_deps` 到 `src/codegen/emit_js/deps.rs`，并补充依赖判定与排序稳定性单测。
+  - 已完成子任务：抽离 `write_file_if_changed` / `is_js_unavailable_procs` / `cirru_to_js` 到 `src/codegen/emit_js/helpers.rs`，并补充基础单测。
+  - 当前策略：每次只做一个低风险子模块迁移，迁移后立即执行定向测试 + `yarn check-all`。
+  - 下一批拆分清单（按顺序执行）：
+    - [x] 抽离 `get_proc_prefix` / `is_cirru_string` 到 `src/codegen/emit_js/runtime.rs`。
+    - [x] 评估并抽离参数拼接相关 helper（已完成 `gen_args_code` + `gen_call_args_with_temps`）。
+    - [x] 评估并抽离 `contains_symbol` + 依赖排序工具（若仅内部使用则独立 `deps.rs`）。
+    - [x] 抽离通用 helper（`write_file_if_changed` / `is_js_unavailable_procs` / `cirru_to_js`）。
+- [x] `DONE` 收敛 runtime helper 分组与导出边界。
+  - [x] 已完成：将 arity helper（`_args_throw` / `_args_fewer_throw` / `_args_between_throw`）抽离到 `ts-src/js-arity-helpers.mts`。
+  - [x] 已完成：将 tag helper（`init_tags`）抽离到 `ts-src/js-tag-helpers.mts`。
+  - [x] 已完成：通过 `calcit.procs.mts` 统一 re-export，保持对外 API 名称不变。
+  - [x] 已完成：补充 runtime helper 分组说明文档（最小化一段说明，记录导出边界）。
+  - 分组边界说明：
+    - `js-arity-helpers.mts` 仅承载参数个数校验错误构造（返回 `Error`，不包含业务逻辑）。
+    - `js-tag-helpers.mts` 仅承载 tag 初始化与缓存（`init_tags` + 内部 `_tag_cache`）。
+    - `calcit.procs.mts` 作为聚合入口，负责稳定导出名，不承载上述 helper 的实现细节。
+
+验收标准：
+
+- 模块文件体量下降、职责更聚焦；
+- 无行为变化，测试与 `check-all` 全通过。
+
+### Milestone C（工程化现代化）
+
+- [ ] `TODO` 引入 benchmark harness（优先 tail recursion/tag/rest 路径）。
+- [ ] `TODO` 评估并设计 workspace 拆分方案（先设计后实施）。
+
+验收标准：
+
+- 基准可重复执行并有基线数据；
+- workspace 拆分有明确边界与迁移顺序。
+
+## AI 协作导向的深层规划（在关键语义不动摇前提下）
+
+目标约束（保持不变）：
+
+- snapshot / 不可变数据模型；
+- trait 体系与 impl 优先级语义；
+- 宏展开能力与 hygienic 机制；
+- JS 编译目标与运行时兼容边界。
+
+核心方向（为 AI “错误左移 + 用法发现”服务）：
+
+1. **把左移内建到语言管线**：
+
+- 在 reader / macroexpand / preprocess / eval 各阶段输出结构化诊断，避免问题漏到下游才暴露。
+
+2. **把诊断做成机器可消费格式**：
+
+- 每条错误/告警包含固定字段：阶段、错误码、主消息、期望、实际、定位信息、建议修复动作。
+
+3. **把“正确用法”绑定到报错上下文**：
+
+- 对常见误用（let 绑定、method 调用、trait 实现、tag-match、可调用对象）附上最小可运行示例或提示入口。
+
+近期执行（已调整）：
+
+- [x] 移除价值较低的独立错误脚本，避免维护“脚本层契约”偏离语言内核演进目标。
+- [x] 结构化诊断 v1 已起步：`LocatedWarning` 增加 `code/hint` 字段，并在 preprocess callable 检查接入首批错误码。
+- [x] 已回退复杂诊断输出，当前统一使用文本诊断与 call stack/examples 指引。
+- [x] `eval` 场景已补充 fallback 映射：参数类型错(`P_ARG_TYPE_MISMATCH`)与非可调用操作符(`P_NON_OPERATOR`)可直接结构化输出。
+- [x] 增加宏诊断协议（code/expected/actual/action/bad/good/rule）与 CLI 解析，输出 `learning` 字段提升 LLM 学习效率。
+- [x] 扩展高频宏入口 shape 校验（fail-fast），减少错误下沉到 `if` 等下游展开节点。
+- [x] 修复兼容性回归并恢复主路径：`fn ()` 保持返回 `nil`，`defrecord` 保持扁平字段写法兼容（如 `defrecord Cat :name :color`）。
+- [x] 保留并强化主路径回归：`test.cirru` + `yarn check-all`（已恢复通过）。
+
+下一步建议（优先级顺序）：
+
+- [ ] 将当前 warning 结构扩展为统一 `CalcitDiagnostic`（含 phase/expected/actual/action），并继续覆盖 preprocess 其余高频场景。
+- [ ] 为高频误用继续补齐错误码与修复提示模板（trait/tag-match/arity 等）。
+- [ ] 为 eval 运行时错误补齐更多 fallback 规则（如 arity/tag-match）并加最小回归样例。
+- [ ] 将宏诊断协议推广到更多核心宏（if/defn/assert-\*），并补 macro-level golden 诊断样例。
+- [ ] guidebook 增加 “AI 友好排错路径” 与 “从错误到修复”最短闭环示例。
+- [ ] 补充“宏入口校验兼容矩阵”文档，明确哪些宏允许空 body/扁平字段等历史语法，防止后续误收紧。

package/rfc/02-17-register-platform-api-rfc.md

@@ -0,0 +1,115 @@
+# RFC: Register API / Host Capability 规范化（与当前实现对齐）
+
+状态：Draft  
+作者：Copilot（基于当前代码审阅）  
+日期：2026-02-17
+
+---
+
+## 1. 背景
+
+Calcit 当前已经具备两套能力：
+
+- 内建 proc/syntax（语言核心）
+- 宿主注入 proc（`register_import_proc*`）
+
+同时 FFI 入口已采用旧命名风格并在当前代码中稳定运行：
+
+- `&call-dylib-edn`
+- `&call-dylib-edn-fn`
+- `&blocking-dylib-edn-fn`
+
+ABI 版本当前为：`0.0.9`（保持不变）。
+
+---
+
+## 2. 当前事实（对应现状）
+
+### 2.1 注册链路
+
+- 注册表：`IMPORTED_PROCS`
+- 元数据表：`IMPORTED_PROC_DESCRIPTORS`
+- 注册入口：
+  - `register_import_proc(name, f)`
+  - `register_import_proc_with_descriptor(name, f, descriptor)`
+- 调用入口：`call_registered_proc(alias, args, call_stack)`
+
+### 2.2 已落地校验能力
+
+descriptor 已用于统一校验：
+
+- 参数个数（`arity_min` / `arity_max`）
+- 平台可用性（`platforms`）
+- 回调最后位约束（`callback_last`）
+- 稳定级别 warning（`stability` + once-warning）
+
+### 2.3 FFI 注入与命名
+
+当前注入保持旧命名风格：
+
+- `&call-dylib-edn`
+- `&call-dylib-edn-fn`
+- `&blocking-dylib-edn-fn`
+
+这与 `dylib-workflow` 当前调用方式一致。
+
+---
+
+## 3. 目标（不引入破坏性变更）
+
+1. 保持旧 FFI 命名不变，减少用户侧迁移成本。
+2. 在不改 ABI（`0.0.9`）前提下继续完善 descriptor 治理能力。
+3. 统一错误语义，避免 FFI 边界 panic 直接外露。
+4. 为后续平台能力文档化提供稳定基础。
+
+---
+
+## 4. 非目标
+
+- 不在当前阶段切换为新命名空间形式（如 `calcit.ffi/*`）。
+- 不在当前阶段升级 ABI 主/次版本。
+- 不尝试统一 Rust 与 JS 的异步模型。
+
+---
+
+## 5. 建议路线
+
+### Phase A（当前可持续）
+
+- 继续使用旧 FFI 命名。
+- 把 descriptor 作为 host proc 的默认治理入口。
+- 保持 ABI `0.0.9`。
+
+### Phase B（增强稳定性）
+
+- 统一 FFI 错误映射（符号缺失、ABI 不匹配、参数错误）。
+- 补齐文档中的平台可用性与调用约束说明。
+
+### Phase C（未来可选）
+
+- 若确有收益，再讨论命名空间 API 与 ABI 演进。
+- 必须先提供迁移文档与自动检查脚本，再做切换。
+
+---
+
+## 6. 验收标准（当前版本）
+
+1. `dylib-workflow` 在旧命名下可直接 `cr -1` 通过。
+2. `call_registered_proc` 校验（arity/platform/callback）持续生效。
+3. ABI 版本保持 `0.0.9` 且调用链稳定。
+4. 相关测试保持通过（Rust tests + workflow 冒烟）。
+
+---
+
+## 7. 决策记录（本轮）
+
+- 采用旧命名风格优先（兼容优先）。
+- 保留并继续使用 descriptor 机制（治理优先）。
+- ABI 不变（风险控制优先）。
+
+---
+
+## 8. 后续维护建议
+
+- 任何涉及 FFI 命名或 ABI 的讨论，都应先更新本 RFC。
+- 若未来开启迁移，需在本 RFC 中追加“兼容窗口 / 回滚策略 / CI 检查项”。

package/rfc/02-18-language-theory-evolution-plan.md

@@ -0,0 +1,367 @@
+# 语言理论演进计划（law / 抽象层 / 类型驱动错误）
+
+状态：Active  
+作者：Chen + Copilot（整理稿）  
+日期：2026-02-17
+
+> 注（2026-02-18）：`laws` 相关实现已从运行时与宏中回退，当前文档仅作为未来迭代指导，不代表已上线能力。
+
+---
+
+## 1. 目标
+
+基于当前 Calcit 工程现实，**逐步**推进到更“理论可解释”的语言形态，重点覆盖：
+
+1. trait 体系补齐“法则层”（laws）与默认验证机制。
+2. 把抽象层从 runtime 规则堆叠，收敛为“核心语义 + 推导扩展”。
+3. 将错误报告升级为“类型驱动开发”导向（给出下一步重构建议）。
+
+非目标：
+
+- 不在单个版本内做破坏性重写。
+- 不先追求完整 Haskell 化（高阶类型系统/纯粹 effect 全量引入）。
+- 不牺牲当前可运行与可迁移性。
+
+---
+
+## 2. 当前问题快照
+
+### 2.1 trait 缺少 law 层
+
+现状：`deftrait`/`defimpl`/`impl-traits` 提供了接口与实现绑定，但缺少“应满足的代数法则”声明与验证。
+
+影响：
+
+- 同一 trait 的不同实现行为可能不可替换。
+- 文档约定无法自动校验，长期容易语义漂移。
+
+### 2.2 抽象层偏实现导向
+
+现状：不少能力以 runtime 规则累积推进，缺少“核心语义 -> 语法糖/能力层”的清晰分层。
+
+影响：
+
+- 新功能进入时容易引入特例。
+- 语义一致性与可证明性不足。
+
+### 2.3 错误报告仍偏“报错”
+
+现状：已有 hint，但多数错误仍偏“指出失败点”，不够“指导下一步重构”。
+
+影响：
+
+- 学习与调试成本偏高。
+- 类型系统价值不能完全转化为开发体验。
+
+---
+
+## 3. 总体演进策略
+
+采用“三阶段、可回滚”的增量路线：
+
+- **Phase A（最低风险）**：把规范写成机器可读元数据，先做到“可声明”。
+- **Phase B（中风险）**：把声明接入检查器与测试框架，做到“可验证”。
+- **Phase C（中高风险）**：把错误系统升级为“诊断 + 修复建议”，做到“可引导重构”。
+
+每阶段都要求：
+
+- 保持向后兼容（默认不破坏旧代码）。
+- 提供 feature flag 或可配置开关。
+- 提供对应 smoke tests。
+
+### 3.1 保守试验约束（新增）
+
+为避免解释器复杂度上升，所有试验默认遵循：
+
+1. **解释器不增新分支**：不在 `evaluate_expr/call_expr` 增加语义特判。
+2. **优先做推导层**：先在 preprocess、lint、测试框架、文档元数据落地。
+3. **语法新增先“可降级”**：任何新声明都能被忽略或展开成现有语义。
+4. **失败可回滚**：用 feature flag 控制，默认关闭或 warning 模式。
+
+可接受改动层级（按优先顺序）：
+
+- 第一层：文档规范、元数据结构、CI 检查。
+- 第二层：preprocess 诊断、`cr` 子命令扩展。
+- 第三层：runtime 文案增强（不改求值语义）。
+
+不建议在早期做的事：
+
+- 新运行时值类型。
+- 新求值规则（尤其是调用/绑定语义）。
+- 影响现有宏展开稳定性的语法硬切换。
+
+---
+
+## 4. 分阶段计划
+
+## Phase A：law 声明与语义分层清单（2~4 周）
+
+### A1. trait law 声明（仅声明，不强制）
+
+新增可选语法（草案级）：
+
+- 在 `deftrait` 中增加 `:laws` 区域，支持命名 law 与谓词模板。
+- 支持 `:doc` / `:examples` 附带 law 说明。
+
+示意：
+
+- `Semigroup`: associativity
+- `Monoid`: associativity + identity
+- `Functor`: identity + composition
+
+### A2. 核心语义分层文档化
+
+建立一份“核心语义边界表”：
+
+- Core（必须稳定）：值模型、调用语义、绑定规则、模式匹配核心。
+- Derived（可演进）：语法糖、宏扩展、宿主能力包装。
+- Host（平台相关）：FFI、IO、环境能力。
+
+要求每个新增功能在 PR 中标注所属层级。
+
+### A3. 错误码分类（不改文案结构）
+
+先统一错误类别枚举映射：
+
+- type-mismatch
+- arity-mismatch
+- trait-law-violation（预留）
+- unresolved-symbol
+- platform-capability
+
+> 先做分类，不强推文案重写。
+
+### Phase A DoD
+
+1. 至少 2 个核心 trait 支持 `:laws` 声明（可空实现）。
+2. 发布“语义分层清单”并接入开发文档。
+3. 错误分类映射在 runtime/preprocess 输出链路可查询。
+
+---
+
+## Phase B：law 验证与抽象层约束落地（3~6 周）
+
+### B1. law-check 框架
+
+增加专用测试入口（例如 `check-laws`）：
+
+- 对声明了 law 的 trait，运行样例驱动验证。
+- 支持“最小样例集 + 可扩展随机样例（可选）”。
+
+默认策略：
+
+- CI 先 warning 模式。
+- 稳定后可在特定 trait 升级为 fail-on-violation。
+
+### B2. 抽象层准入规则
+
+新增 lint/CI 规则：
+
+- Core 层禁止直接依赖 Host 能力。
+- Derived 层新增语法糖时必须给出 core 等价展开。
+- Host 能力必须显式标注平台与稳定级别。
+
+### B3. trait 冲突的结构化报告
+
+对于方法名冲突，不只提示“有冲突”，还输出：
+
+- 冲突来源 trait 列表。
+- 当前选择路径（precedence）。
+- 推荐解法（显式 trait-call / 重命名 / 调整 impl 顺序）。
+
+### Phase B DoD
+
+1. 至少 1 个 trait（例如 `Monoid` 或 `Functor`）有可执行 law-check。
+2. CI 能检查核心分层违规。
+3. 冲突诊断包含“来源 + 选择 + 修复路径”。
+
+---
+
+## Phase C：类型驱动错误与重构建议（4~8 周）
+
+### C1. 诊断从“错误”升级为“问题卡片”
+
+每条关键错误输出统一包含：
+
+- What happened
+- Why（类型/语义原因）
+- Next 1~2 actions（可执行）
+- 示例链接（如 `query examples`）
+
+### C2. 常见模式自动修复建议
+
+先覆盖高频场景：
+
+- 参数个数错误 -> 建议签名/调用最小改法。
+- trait 缺失 -> 建议 `assert-traits` / `impl-traits` 路径。
+- 平台能力错误 -> 建议替代 API 或运行目标。
+
+### C3. 类型驱动提示入口
+
+给开发流程增加一条轻量入口：
+
+- `cr doctor`（草案）或现有命令扩展，汇总当前文件“下一步可修复项”。
+
+### Phase C DoD
+
+1. 三类高频错误具备标准化重构建议。
+2. 错误信息可稳定指向文档/示例。
+3. 团队内部试用反馈中，“看报错后可直接行动”的比例显著提升。
+
+---
+
+## 5. 风险与缓解
+
+- 风险：law 语法过早固化导致后续包袱。
+  - 缓解：Phase A 仅声明，不强制；保留实验标记。
+
+- 风险：验证框架引入 CI 波动。
+  - 缓解：先 warning，再逐步提升到 fail。
+
+- 风险：错误文案重写工作量大。
+  - 缓解：优先高频 20% 场景，分批覆盖。
+
+---
+
+## 6. 推荐优先级（马上可做）
+
+1. 先落地 Phase A（声明与分层）——最小改动、收益清晰。
+2. 在 trait 体系选一个样板 trait 做 law-check 试点。
+3. 把错误输出模板统一成“问题卡片”结构（先不做自动修复）。
+
+### 6.1 三个“推导式优先”试点（可立即开始）
+
+#### 试点 A：Law 只做元数据 + 测试映射
+
+- 在 trait 文档/定义处声明 law 名称，不改变运行时行为。
+- 由 `check-laws`（或测试脚本）把 law 名称映射到现有测试样例。
+- 解释器零改动；收益是“语义约束可追踪”。
+
+#### 试点 B：抽象分层只做 CI 准入
+
+- 给模块或 PR 增加 `core/derived/host` 标签。
+- 用静态规则检查“core 不可依赖 host”。
+- 不改运行时；收益是“架构边界可持续维护”。
+
+#### 试点 C：错误卡片先由 preprocess 生成
+
+- 保留现有错误类型，仅在 preprocess 侧补 `Why/Next`。
+- 对高频 3 类错误做模板化建议（arity、trait 缺失、平台能力）。
+- 不改解释器求值；收益是“开发体验立即提升”。
+
+#### 试点评估门槛（继续/停止）
+
+- 两周内若满足以下至少两项，则继续推进：
+  - 同类问题二次出现率下降。
+  - 平均修复轮次下降。
+  - PR review 在语义争议上的耗时下降。
+
+- 若不满足，则回滚到“仅文档+检查”层，不进入 runtime。
+
+---
+
+## 7. 评估指标（建议）
+
+- 语义一致性：同 trait 多实现的行为偏差问题数量。
+- 可维护性：新增功能触发的特例分支数。
+- 开发体验：错误到修复的平均迭代次数。
+- 迁移成本：现有项目升级失败率与修复时长。
+
+---
+
+## 8. 结论
+
+这条路线的核心不是“追求学术完整度”，而是把学术语言里最有价值的三个能力逐步工程化：
+
+- **可声明的语义约束（laws）**
+- **可解释的抽象分层（core/derived/host）**
+- **可执行的错误引导（type-driven diagnostics）**
+
+在不破坏现有生态的前提下，这能持续提升 Calcit 的理论一致性与工程可用性。
+
+---
+
+## 9. 直接执行清单（不拆 issue）
+
+以下清单按“尽量不增加解释器复杂度”设计，优先修改文档、preprocess、测试和 CLI 提示层。
+
+### 9.1 第 1 步：先把 law 变成可追踪元数据（仅声明）
+
+目标：不改求值语义，只让 trait 能表达 law 信息，并可在文档/工具中读取。
+
+建议改动：
+
+- 在 trait 相关文档中增加 law 字段约定（先文档约束，再代码约束）。
+- 在 `deftrait` 相关 preprocess 路径中允许读取 `:laws`（可选，不填不影响）。
+- law 内容先支持简单命名：`associativity`、`identity`、`composition`。
+
+验收标准：
+
+- 不带 `:laws` 的旧代码保持行为一致。
+- 带 `:laws` 的定义在 preprocess 阶段可被识别并保留元信息。
+
+当前状态：
+
+- 暂缓执行，代码侧未启用该能力。
+- 继续保留为后续设计入口，待语义收益明确后再推进。
+
+### 9.2 第 2 步：增加一个最小 law-check 入口（warning 模式）
+
+目标：用现有测试体系验证 law，不引入新运行时规则。
+
+建议改动：
+
+- 增加一个命令入口（可在 `cr` 子命令或测试脚本中实现）用于执行 law-check。
+- 先对 1 个 trait 做样板（建议 `Monoid` 或 `Semigroup`）。
+- 输出为 warning，不阻断主流程。
+
+验收标准：
+
+- 能输出“哪个 law 失败 + 最小反例（若可得）”。
+- 对没有 law 声明的 trait 不做额外检查。
+
+### 9.3 第 3 步：错误卡片化（先做 3 类高频）
+
+目标：保留原错误类型，增强诊断信息为“可执行下一步”。
+
+先覆盖：
+
+- arity 错误
+- trait 缺失/方法冲突
+- 平台能力不匹配（如 registered proc 平台限制）
+
+统一模板：
+
+- What happened
+- Why
+- Next actions（1~2 条）
+
+验收标准：
+
+- 现有错误 kind 不变（兼容上层逻辑）。
+- 至少 3 类错误能稳定输出 Next actions。
+
+### 9.4 第 4 步：分层准入只在 CI 做
+
+目标：限制复杂度扩散，不在 runtime 加硬编码分层判断。
+
+建议改动：
+
+- 增加轻量规则：Core 不直接依赖 Host。
+- Derived 功能需提供 core 等价展开说明（文档或注释）。
+
+验收标准：
+
+- 新增功能 PR 必须标注层级（core/derived/host）。
+- 规则触发时给出明确修复建议，而不是仅失败。
+
+### 9.5 建议执行顺序与命令
+
+推荐顺序：`9.1 -> 9.2 -> 9.3 -> 9.4`。
+
+每步完成后建议执行：
+
+- `cargo test`
+- `yarn check-all`
+
+如果某步导致复杂度明显上升（新增解释器分支、语义特判），则回滚到上一步，仅保留文档/检查器侧改动。