@calcit/procs 0.12.19 → 0.12.20

package/rfc/03-18-query-def-tree-show-chunked-display-plan.md

@@ -0,0 +1,301 @@
+# `cr query def` / `cr tree show` 分片展示方案
+
+## 目标
+
+当定义或子树比较小时，继续保持当前直接输出的体验。
+
+当表达式足够大时，切换到“分片展示”模式，满足下面几点：
+
+- 保留一个可快速阅读的根视图；
+- 用占位符替换体积过大的子树；
+- 按坐标顺序输出被拆出的片段；
+- 允许通过参数调整每个片段期望容纳的节点数；
+- 输出与文档优先使用点号路径，同时兼容逗号路径输入。
+
+## 选定案例
+
+本次以 `find-children-diffs` 作为主案例。
+
+原因：
+
+- 它已经足够大，能明显暴露当前整块输出的可读性问题；
+- 它内部天然存在 `cond`、嵌套 `let`、局部分支组等适合作为切分边界的结构；
+- 它贴近真实工作流，既适合人阅读，也适合作为 LLM 分治理解的目标。
+
+## 对比结论
+
+### 基线：直接整块输出
+
+当前的 `cr query def` 会一次性打印完整定义。
+
+当前的 `cr tree show` 会打印目标子树，然后列出直接子节点路径。
+
+这个方案在小表达式上没有问题，但面对大表达式时会出现这些缺点：
+
+- 主流程和局部细节混在一起，不容易先抓到整体结构；
+- 重复性的局部绑定会占掉大量屏幕；
+- 用户必须反复在 `search`、`show`、原始代码块之间切换；
+- LLM 容易被附近细节吸住，反而丢掉更高层的分支关系。
+
+### 1 倍预算
+
+较早实验里，`find-children-diffs` 的目标片段大小大约是 `24` 个节点。
+
+这一版会被拆成 `14` 个片段，很多片段落在 `19-39` 节点之间。结构虽然有效，但整体仍然偏碎，不利于连续阅读。
+
+### 2 倍预算
+
+把目标片段大小提高到大约 `48` 个节点后，同一个案例会变成 `9` 个片段：
+
+- `75, 57, 55, 53, 53, 42, 41, 39, 35`
+
+这一版更适合作为默认方案，原因是：
+
+- 顶层控制流可以一眼看清；
+- 局部初始化逻辑更容易整体保留；
+- 片段数足够少，可以顺序浏览；
+- 切分边界看起来更接近语义单元，而不是机械按大小切开。
+
+## 表达式拆分示例
+
+下面用一个简化的表达式说明“整块输出”和“分片输出”的区别。
+
+原始表达式：
+
+```cirru
+let
+    a $ compute-a x
+    b $ compute-b x
+  cond
+      ready? a b
+      handle-ready a b
+    fallback?
+      let
+          details $ build-details a b
+          view $ render-view details
+        emit! view
+        track! details
+    true
+      let
+          err $ build-error a b
+        warn err
+        recover err
+```
+
+分片展示后，根片段会更像这样：
+
+```cirru
+ROOT at root
+let
+    a $ compute-a x
+    b $ compute-b x
+  cond
+      ready? a b
+      handle-ready a b
+    fallback?
+      {{let_emit_track_01}}@2.2
+    true
+      {{let_warn_recover_02}}@2.3
+```
+
+再继续列出拆出的片段：
+
+```cirru
+{{let_emit_track_01}} at 2.2
+let
+    details $ build-details a b
+    view $ render-view details
+  emit! view
+  track! details
+
+{{let_warn_recover_02}} at 2.3
+let
+    err $ build-error a b
+  warn err
+  recover err
+```
+
+这样做的好处是：
+
+- 根片段只保留主流程；
+- 细节块被移动到后面，阅读顺序更清晰；
+- 每个占位符都带精确坐标，仍然能回到原树上继续定位或编辑。
+
+## 决策
+
+默认采用“递归语义切分”作为大表达式的展示策略。
+
+更具体地说：
+
+- 以现有递归语义启发式为基础；
+- 只有当表达式超过某个可配置阈值时才启用分片；
+- 默认预算采用比早期实验更宽松的配置；
+- 保留 `--raw` 作为脚本和精确检查时的逃生口。
+
+## 预期交互
+
+### `cr query def`
+
+对于较小定义：
+
+- 保持现在的直接输出。
+
+对于较大定义：
+
+- 元信息照常输出；
+- 用 `Chunked Cirru:` 替代一整块超长 Cirru；
+- 先打印根片段，再按坐标顺序打印拆出的片段；
+- 每个片段展示：坐标、节点数、最大深度、Cirru 内容。
+
+### `cr tree show`
+
+对于较小子树：
+
+- 保持现在的输出形状。
+
+对于较大子树：
+
+- 先展示节点类型和子树统计；
+- 再展示分片后的根预览；
+- 后续继续列出拆出的片段；
+- 子节点导航提示仍然基于原始树路径；
+- 用户可以直接根据片段坐标继续向下钻取。
+
+## CLI 参数设计
+
+这些参数应同时提供给 `cr query def` 和 `cr tree show`：
+
+- `--chunk-target-nodes <n>`：每个片段理想节点数；
+- `--chunk-max-nodes <n>`：停止继续细分前允许的软上限；
+- `--chunk-trigger-nodes <n>`：总节点数低于该值时不启用分片；
+- `--raw`：强制回退到旧的整块输出。
+
+当前建议默认值：
+
+- `chunk-target-nodes = 56`
+- `chunk-max-nodes = 68`
+- `chunk-trigger-nodes = 88`
+
+原因：
+
+- `target` 需要足够大，避免过度切碎；
+- `max` 略高于 `target`，避免为了几颗节点继续无意义细分；
+- `trigger` 需要过滤掉本来还能整体阅读的中等表达式。
+
+## 路径方案
+
+### 输出格式
+
+所有新的展示输出统一优先使用点号路径，例如：
+
+- `3.2.4.1.1`
+
+这样和前面的分片研究保持一致，也更方便人和 LLM 直接复制。
+
+### 输入兼容
+
+路径输入保持两种写法都支持：
+
+- 逗号：`3,2,4,1,1`
+- 点号：`3.2.4.1.1`
+
+规则：
+
+- 空字符串仍表示根节点；
+- 同一路径里混用点号和逗号时直接报错，避免静默歧义；
+- 文档只主推点号写法，逗号作为兼容行为说明一次即可。
+
+## 内部实现计划
+
+### 1. 提取可复用的分片模块
+
+把展示侧的切分逻辑从实验脚本迁移到 Rust，形成独立的 CLI 辅助模块。
+
+职责包括：
+
+- 计算节点统计信息；
+- 收集候选子树；
+- 基于递归语义策略选择切点；
+- 生成占位符；
+- 输出有序分解结果；
+- 统一格式化路径。
+
+### 2. 第一阶段只做展示层改造
+
+第一阶段不修改 snapshot 存储、不修改 AST 语义、不修改编辑行为。
+
+仅让 `query def` 与 `tree show` 使用新的分片渲染。
+
+### 3. 集中处理路径兼容
+
+扩展公共路径解析逻辑，让各 CLI handler 都能接受点号路径，而不是每个命令各自手写兼容。
+
+同时增加统一的路径格式化函数，避免到处手写 `join(",")` 或 `join(".")`。
+
+### 4. 更新命令处理逻辑
+
+`handle_def`：
+
+- 先计算定义总节点数；
+- 根据阈值决定直接输出还是分片输出；
+- 保持 `--json` 行为不变。
+
+`handle_show`：
+
+- 先计算目标子树节点数；
+- 根据阈值决定直接输出还是分片输出；
+- 保持子节点导航提示和替换提示。
+
+### 5. 文档迁移
+
+把文档示例统一调整为优先使用点号路径，例如：
+
+```bash
+cr tree show ns/def -p '3.2.1'
+```
+
+逗号兼容只在合适位置说明一次，不重复铺满全文。
+
+## 风险与应对
+
+### 风险：展示过于“魔法化”
+
+应对：
+
+- 保留 `--raw`；
+- 明确打印分片统计信息；
+- 每个片段都保留精确坐标。
+
+### 风险：点号路径与命名空间里的点冲突
+
+应对：
+
+- 点号/逗号解析只作用于路径参数；
+- 不把这套解析逻辑用于 `ns/def` 目标字符串。
+
+### 风险：分片展示影响编辑工作流
+
+应对：
+
+- 分片只影响展示，不影响数据结构；
+- 真正的编辑命令仍然对原始树坐标生效。
+
+## 推进顺序
+
+1. 先写这份方案文档。
+2. 在 Rust 中加入可复用的分片与路径辅助逻辑。
+3. 把分片渲染接入 `cr query def`。
+4. 把分片渲染接入 `cr tree show`。
+5. 加入点号路径兼容。
+6. 更新文档，主推点号路径。
+7. 用 `find-children-diffs` 做真实案例验证，并微调默认值。
+
+## 验收标准
+
+- `cr query def` 在大定义上默认输出分片结果；
+- `cr tree show` 在大子树上默认输出分片结果；
+- 两个命令都支持 `--chunk-target-nodes`；
+- 两个命令都接受点号路径；
+- 逗号路径保持兼容；
+- 文档示例优先使用点号路径；
+- `--raw` 可以恢复旧的整块输出行为。

package/rfc/04-13-call-arg-literal-rewrite-rfc.md

@@ -0,0 +1,205 @@
+# RFC: 函数参数字面量自动改写 — Map-to-Record & Tuple-to-Enum
+
+状态：Implemented
+日期：2026-04-13
+
+---
+
+## 1. 概要
+
+在预处理阶段，当函数参数的 schema 标注引用了具体类型（struct 或 enum）时，允许调用方使用更简洁的字面量语法（hashmap `{}` 或 untyped tuple `::`），由预处理器自动改写为对应的类型化构造表达式（record `%{}` 或 enum tuple `%::`），以便后续类型检查正常工作。
+
+## 2. 动机
+
+### 问题
+
+Calcit 区分"无类型字面量"和"有类型构造"：
+
+- `{} (:x 1) (:y 2)` 创建普通 hashmap，而 `%{} Point (:x 1) (:y 2)` 创建 record。
+- `:: :ok` 创建普通 tuple（无 class 引用），而 `%:: Result0 :ok` 创建 enum tuple（有 class）。
+
+当函数签名明确标注参数类型时，调用者仍需手写完整的类型化构造：
+
+```cirru
+;; 参数标注为 Point record
+defn sum-point (p) ...
+  :: :fn $ {} (:return :number)
+    :args $ [] 'app.main/Point
+
+;; 调用者必须写完整形式
+sum-point $ %{} Point (:x 10) (:y 20)
+```
+
+这在大量调用点重复书写时既冗余又容易出错（特别是忘记加 `%` 前缀）。
+
+### 解法
+
+预处理器根据函数参数的 schema 类型标注，自动将简写形式改写为完整形式：
+
+| 简写 | 改写为 | 触发条件 |
+|---|---|---|
+| `{} (:x 1) (:y 2)` | `%{} Point (:x 1) (:y 2)` | 参数类型为 struct/record |
+| `:: :ok` | `%:: Result0 :ok` | 参数类型为 enum |
+
+改写后的 AST 能正常参与：
+- 运行时类型验证（field 校验、variant 校验）
+- 预处理阶段类型检查（`check_user_fn_arg_types`）
+- JS codegen（通过 Import 引用而非内联 Struct/Enum 值）
+
+## 3. 设计
+
+### 3.1 Map-to-Record 改写
+
+**触发条件：**
+
+1. 函数 schema 的 `:args` 中某位置引用了 struct 类型（`TypeRef`、`Struct` 或 `Record`）
+2. 调用处该位置是 hashmap 字面量（以 `NativeMap` proc 开头的 list）
+3. hashmap 所有 key 都是 tag，且都是目标 struct 的合法字段
+
+**改写规则：**
+
+- `[NativeMap, :k1, v1, :k2, v2]` → `[NativeRecord, struct_ref, :field1, v1_or_nil, :field2, v2_or_nil, ...]`
+- struct 中未提供的字段自动填充 `nil`
+- 字段顺序按 struct 定义排列（非 map 出现顺序）
+- `struct_ref` 优先使用 `Calcit::Import`（带 ns/def 路径），以兼容 JS codegen
+
+**跳过条件（不报错，保持原样）：**
+
+- map 中含有非 tag 的 key
+- map 中含有 struct 不存在的字段名
+- 无法从 schema 解析出 struct 定义
+
+**示例：**
+
+```cirru
+defstruct Point (:x :number) (:y :number)
+
+defn sum-point (p)
+  :: :fn $ {} (:return :number)
+    :args $ [] 'app.main/Point
+  &+ (:x p) (:y p)
+
+;; 简写
+sum-point $ {} (:x 10) (:y 20)
+;; 预处理改写为
+sum-point $ %{} Point (:x 10) (:y 20)
+```
+
+### 3.2 Tuple-to-Enum 改写
+
+**触发条件：**
+
+1. 函数 schema 的 `:args` 中某位置引用了 enum 类型（`TypeRef`、`Enum` 或 `Tuple`）
+2. 调用处该位置是 untyped tuple 字面量（以 `NativeTuple` proc 开头的 list）
+
+**改写规则：**
+
+- `[NativeTuple, :tag, payload...]` → `[NativeEnumTupleNew, enum_ref, :tag, payload...]`
+- `enum_ref` 优先使用 `Calcit::Import`（带 ns/def 路径），以兼容 JS codegen
+- 不验证 tag 或 payload（由后续 `check_enum_tuple_construction` 完成）
+
+**跳过条件（不报错，保持原样）：**
+
+- tuple 字面量没有 tag（空 `::` 表达式）
+- 无法从 schema 解析出 enum 定义
+
+**示例：**
+
+```cirru
+defenum Result0 (:err :string) (:ok)
+
+defn takes-result (r)
+  :: :fn $ {} (:return :dynamic)
+    :args $ [] 'app.main/Result0
+  tag-match r ((:ok) :ok) ((:err msg) msg) $ _ :unknown
+
+;; 简写
+takes-result $ :: :ok
+;; 预处理改写为
+takes-result $ %:: Result0 :ok
+
+;; 带 payload
+takes-result $ :: :err |error-msg
+;; 预处理改写为
+takes-result $ %:: Result0 :err |error-msg
+```
+
+## 4. 实现
+
+### 4.1 类型解析
+
+在 `CalcitTypeAnnotation` 上新增方法：
+
+| 方法 | 用途 |
+|---|---|
+| `resolve_to_struct_with_ref()` | 解析 struct + 可选 (ns, def) 路径（已有） |
+| `resolve_to_enum_with_ref()` | 解析 enum + 可选 (ns, def) 路径（新增） |
+
+两者都处理 `Struct/Record`↔`Enum/Tuple` 直接值、`TypeRef("ns/def")` 程序查找、以及 `Optional(inner)` 解包。
+
+底层依赖：
+
+| 函数 | 用途 |
+|---|---|
+| `resolve_struct_from_program(ns, def)` | 从 program registry 查找 struct 定义（已有） |
+| `resolve_enum_from_program(ns, def)` | 从 program registry 查找 enum 定义（新增） |
+
+### 4.2 改写函数
+
+| 函数 | 用途 |
+|---|---|
+| `try_rewrite_map_args_to_records()` | 遍历参数列表，对 map 字面量尝试改写（已有） |
+| `try_rewrite_single_map_to_record()` | 单个参数的 map→record 改写（已有） |
+| `try_rewrite_tuple_args_to_enum_tuples()` | 遍历参数列表，对 tuple 字面量尝试改写（新增） |
+| `try_rewrite_single_tuple_to_enum_tuple()` | 单个参数的 tuple→enum-tuple 改写（新增） |
+
+### 4.3 集成点
+
+在 `preprocess_list_call()` 的 `Fn` 分支中，按顺序调用：
+
+1. `try_rewrite_map_args_to_records()` — map → record
+2. `try_rewrite_tuple_args_to_enum_tuples()` — tuple → enum tuple
+3. `check_core_fn_arg_types()` — 内建函数参数类型检查
+4. `check_user_fn_arg_types()` — 用户函数参数类型检查
+
+两次改写串联：第一次的输出作为第二次的输入。
+
+### 4.4 JS Codegen 兼容
+
+改写时若从 `TypeRef` 解析出 (ns, def) 路径，会构造 `Calcit::Import` 而非内联的 `Calcit::Struct`/`Calcit::Enum`。这是因为 JS codegen 不支持直接 emit `Struct`/`Enum` 字面量——它需要一个变量引用。
+
+Import 策略：
+- 同 namespace → `ImportInfo::SameFile`
+- 跨 namespace → `ImportInfo::NsReferDef`
+
+### 修改的文件
+
+| 文件 | 变更 |
+|---|---|
+| `src/calcit/type_annotation.rs` | `resolve_to_enum_with_ref()`, `resolve_enum_from_program()` |
+| `src/runner/preprocess.rs` | `try_rewrite_tuple_args_to_enum_tuples()`, `try_rewrite_single_tuple_to_enum_tuple()`，集成到 Fn 分支 |
+| `docs/features/enums.md` | 新增 "Automatic Tuple-to-Enum Rewrite" 章节 |
+| `docs/features/records.md` | "Automatic Map-to-Record Rewrite" 章节（已有） |
+| `calcit/test-enum.cirru` | 新增 `test-tuple-to-enum` 测试 |
+
+## 5. 测试覆盖
+
+### Map-to-Record（已有）
+
+- `calcit/test-record.cirru` 中 `test-map-to-record`
+  - `sum-point $ {} (:x 10) (:y 20)` → 验证返回值正确
+  - `check-point-type $ {} (:x 10) (:y 20)` → 验证改写后值为 record 类型
+
+### Tuple-to-Enum（新增）
+
+- `calcit/test-enum.cirru` 中 `test-tuple-to-enum`
+  - `takes-result $ :: :ok` → 验证 tag-match 匹配
+  - `takes-result $ :: :err |error-msg` → 验证 payload 传递
+  - `check-result-type $ :: :ok` → 验证改写后值有 enum origin
+
+## 6. 局限性
+
+- **仅作用于直接字面量**：传递变量（即使值是 map/tuple）不会触发改写，因为预处理阶段无法确定变量的运行时值。
+- **不验证内容**：map-to-record 验证 key 是否为合法字段，tuple-to-enum 不验证 tag 和 payload（由后续的 `check_enum_tuple_construction` 完成）。
+- **无法逆向**：改写后的 AST 无法区分是用户手写的 `%{}` / `%::` 还是改写生成的。调试时看到的都是改写后的形式。
+- **JS codegen 依赖**：如果类型注解是直接的 `Struct(def)` / `Enum(def)` 而非 `TypeRef("ns/def")`，改写会内联结构体/枚举值，在 JS codegen 中可能 panic（目前通过优先使用 TypeRef 规避）。

package/rfc/04-13-type-slot-mechanism-rfc.md

@@ -0,0 +1,194 @@
+# RFC: Type Slot 机制 — 库-应用间的类型注入
+
+状态：Draft
+日期：2025-07-13
+
+---
+
+## 1. 概要
+
+实现 `deftype-slot` / `bind-type` proc 对，允许库代码声明类型占位符（slot），应用代码在启动时绑定具体类型（enum/struct/record）。预处理阶段自动解析 slot 引用，使跨包边界的类型检查成为可能。
+
+## 2. 动机
+
+### 问题
+
+Calcit 的静态类型分析在单包内工作良好：`defenum` 定义的变体名、载荷数量和类型都能在预处理阶段被检查。但当**库**（如 Respo）定义回调签名时，它无法知道**应用**层会使用哪个 enum 作为 dispatch 操作类型。
+
+以 Respo 的 `EventHandler` 为例：
+
+```cirru
+;; respo.schema — 库代码
+;; dispatch 回调的签名原先只能标注为 :tuple（即 Dynamic）
+:: :fn $ {} (:return :unit)
+  :args $ [] '*dispatch-op
+```
+
+应用层定义了自己的 Op enum：
+
+```cirru
+;; app.schema
+defenum Op (:add :string) (:remove :tag) (:toggle :map) (:clear) ...
+```
+
+没有 type-slot 机制时，`d! (: add ...)` 这类调用无法被类型检查，因为预处理器不知道 dispatch 参数应该是 `Op` 类型。
+
+### 为什么不用泛型
+
+Calcit 目前没有完整的泛型（type parameter）系统。引入泛型会大幅增加语言复杂性，而 type-slot 解决的是一个更窄的问题：**跨编译单元的单一类型注入**。它更像 dependency injection 而非 parametric polymorphism。
+
+## 3. 设计
+
+### 核心概念
+
+| 概念 | 说明 |
+|---|---|
+| **Type Slot** | 一个命名占位符，声明时值为 `None`，绑定后值为具体类型注解 |
+| `deftype-slot :name` | 在库代码中声明 slot（通常放在 schema 命名空间） |
+| `bind-type :name ConcreteType` | 在应用入口绑定具体类型（通常放在 `main!` 函数体） |
+| `*name` | 在 schema 类型标注中引用 slot（解析为 `TypeSlot(name)`） |
+
+### 生命周期
+
+```
+声明 (deftype-slot)  →  绑定 (bind-type)  →  解析 (*name 引用)  →  类型检查
+       ↑ 库代码               ↑ 应用入口           ↑ 预处理阶段          ↑ 预处理阶段
+```
+
+1. **声明**：`deftype-slot :dispatch-op` 在 `TYPE_SLOTS` 注册表中插入 `("dispatch-op", None)`。
+2. **绑定**：`bind-type :dispatch-op Op` 将 slot 值设为 `Some(Enum(Op, []))`。绑定发生在预处理阶段（通过 `resolve_program_value_for_preprocess` 提前求值），确保后续同一编译 pass 的类型检查能立即使用。
+3. **解析**：当类型标注遇到 `*dispatch-op` 时，`resolve_type_slot("dispatch-op")` 返回绑定的 `Enum(Op, [])`。
+4. **检查**：解析后的类型委托给标准的 `matches_with_bindings` / `value_matches_type_annotation` 进行检查。
+
+### 约束
+
+- 每个 slot 只能声明一次（重复声明报错）。
+- 每个 slot 只能绑定一次（重复绑定报错）。预处理阶段已完成绑定后，运行时再次执行 `bind-type` 会静默跳过（no-op），不会重复报错。
+- 未绑定的 slot 在类型检查时等同于 `:dynamic`（不报错但不检查）。
+- 绑定必须是 enum、struct 或 record 类型。
+
+## 4. API 参考
+
+### `deftype-slot`
+
+声明一个类型占位符。
+
+```cirru
+deftype-slot :dispatch-op
+```
+
+- **参数**：1 个 tag 或 string，作为 slot 名称。
+- **返回**：`nil`
+- **副作用**：在全局 `TYPE_SLOTS` 注册表中注册 slot。
+
+### `bind-type`
+
+将具体类型绑定到已声明的 slot。
+
+```cirru
+bind-type :dispatch-op Op
+```
+
+- **参数**：
+  1. tag 或 string — slot 名称（必须已通过 `deftype-slot` 声明）。
+  2. enum / struct / record 定义值。
+- **返回**：`nil`
+- **副作用**：将类型绑定写入 `TYPE_SLOTS`。
+- **错误**：slot 未声明、slot 已绑定、第二参数类型不对。
+
+### `*name` 类型引用语法
+
+在 schema 类型标注中使用 `*name` 引用 slot：
+
+```cirru
+;; 在 EventHandler 的 schema 中
+:args $ [] '*dispatch-op
+```
+
+Cirru EDN 序列化为 `'*dispatch-op`（`'` 是 EDN symbol 前缀，`*` 是 type-slot 标记）。
+
+## 5. 使用示例
+
+### Respo EventHandler 场景
+
+**库端（respo.schema）：**
+
+```cirru
+;; 声明 slot
+deftype-slot :dispatch-op
+
+;; EventHandler schema 引用 slot
+:: :fn $ {} (:return :unit)
+  :args $ [] 'respo.schema/RespoEvent
+    :: :fn $ {} (:return :unit)
+      :args $ [] '*dispatch-op
+```
+
+**应用端（app.main）：**
+
+```cirru
+;; app.schema 定义 Op enum
+defenum Op
+  :add :string
+  :remove :tag
+  :toggle :map
+  :update :tag :string
+  :clear
+  :states-merge :any :any :any
+
+;; main! 中绑定
+defn main! ()
+  bind-type :dispatch-op Op
+  ;; ... 后续代码
+```
+
+**效果**：
+
+```cirru
+;; ✅ 正确 — 编译通过
+d! $ %:: Op :toggle (:id task)
+
+;; ❌ 错误变体名 — 预处理警告 "does not have variant :delete"
+d! $ %:: Op :delete (:id task)
+
+;; ❌ 载荷数量错 — 预处理警告 "expects 1 payload(s), got 2"
+d! $ %:: Op :clear 42
+
+;; ❌ 载荷类型错 — 预处理警告 "expects :string, got :number"
+d! $ %:: Op :add 42
+```
+
+## 6. 实现细节
+
+### 修改的文件
+
+| 文件 | 变更 |
+|---|---|
+| `src/calcit/type_annotation.rs` | `TYPE_SLOTS` 注册表, `TypeSlot` 变体, slot 解析/匹配/序列化 |
+| `src/calcit/proc_name.rs` | `DeftypeSlot` / `BindType` proc 名称 |
+| `src/builtins.rs` | dispatch arms |
+| `src/builtins/meta.rs` | `deftype_slot()` / `bind_type()` 实现 |
+| `src/calcit.rs` | re-export `register_type_slot`, `bind_type_slot` |
+| `src/runner.rs` | `clear_type_slots()` 在程序启动时调用（避免跨次运行残留） |
+| `src/runner/preprocess.rs` | 预处理阶段提前执行 `deftype-slot` / `bind-type` |
+
+### 关键实现点
+
+1. **Thread-local 注册表**：`TYPE_SLOTS` 使用 `thread_local! { RefCell<HashMap<...>> }`，因为 `HashMap::new()` 不是 const fn，不能用 `const { ... }` 初始化。
+
+2. **预处理时绑定**：`bind-type` 在预处理阶段通过 `resolve_program_value_for_preprocess()` 提前求值，确保同一编译 pass 内类型检查可以立即使用绑定结果。这是整个机制的关键——如果在运行时才绑定，预处理阶段的类型检查无法看到具体类型。
+
+3. **类型匹配委托**：`TypeSlot` 在 `matches_with_bindings` 和 `value_matches_type_annotation` 中解析后直接委托给标准匹配逻辑，不引入新的匹配分支。
+
+4. **序列化**：`TypeSlot(name)` 序列化为 `Edn::Symbol("*name")`，反序列化时 `*` 前缀触发 `TypeSlot` 解析。
+
+## 7. 局限性与未来方向
+
+- **单绑定约束**：每个 slot 只能绑定一次。如果需要一个库支持多个不同 dispatch 类型或一个项目中有多个不同的 EventHandler，需要声明多个 slot。
+- **无运行时效果**：`deftype-slot` 和 `bind-type` 在运行时是无操作的（返回 nil），它们的作用完全在预处理阶段。
+- **仅支持 enum/struct/record**：不能绑定基础类型（如 `:number`）到 slot，因为 slot 的主要场景是复合类型注入。
+- **未来可扩展**：如果未来 Calcit 引入泛型或 trait 约束，type-slot 可以作为特化机制的基础。
+
+## 8. 从 editing-history 迁移说明
+
+本提案内容源自 `editing-history/202507131553-type-slot-mechanism.md`，已扩充为完整 RFC 格式。原始文件可在合并后删除。