@calcit/procs 0.12.48 → 0.12.50

package/RFCs/07-08-ffi-features-and-js-object-type-rfc.md

@@ -0,0 +1,223 @@
+# RFC: `:features` 函数能力标记 + `:js-object` 类型收敛
+
+状态：Draft
+日期：2026-07-08
+
+---
+
+## 1. 概要
+
+在函数 schema 中新增 `:features` 属性（HashSet），标记当前函数可使用的语言能力子集。默认空集合。使用 JS interop 语法（`aget`、`&js-object`、`new` 等）要求函数显式标记 `:features $ #{} :js-ffi`，从类型层面将 FFI 隔离在有限的 binding 函数中。
+
+同步新增 `:js-object` 类型注解，表示 JavaScript FFI 操作产生的外部 opaque 数据，阻断 JS 对象向纯 Calcit 函数的无意识泄露。
+
+## 2. 动机
+
+### 问题
+
+当前 JS FFI 函数（`is_js_syntax_procs` 收录 21 个）在 `codegen::codegen_mode()` 下全局放行，任何函数都可以随意调用：
+
+```cirru
+;; 任意函数都能直接调用 FFI，无任何约束
+defn my-pure-fn (x)
+  aget x |someProp  ;; 静默通过
+  &js-object $ {} (:a 1)  ;; 静默通过
+```
+
+这导致：
+
+- **边界模糊**：无法从代码中区分"纯 Calcit 函数"和"FFI binding 函数"
+- **审查困难**：排查 JS interop 使用点需要全文搜索 21 个函数名
+- **类型不安全**：JS 对象可以自由流经所有函数，静态分析无法追踪外部数据
+- **重构风险**：修改 FFI 层时无法确定影响范围
+
+### 目标
+
+| 目标     | 说明                                                                     |
+| -------- | ------------------------------------------------------------------------ |
+| 权限收敛 | 只有 schema 中声明 `:js-ffi` 的函数才能调用 JS FFI                       |
+| 类型隔离 | `:js-object` 类型标注 JS 对象，跨非 FFI 边界时产生告警                   |
+| 渐进迁移 | 先 warning 后 error，给生态适配时间                                      |
+| 可扩展   | `:features` 设计预留 `:side-effects`、`:async`、`:unsafe` 等未来能力标记 |
+
+## 3. 设计
+
+### 3.1 `:features` — Schema 属性
+
+在 `CalcitFnTypeAnnotation` 中新增 `features` 字段：
+
+```rust
+pub struct CalcitFnTypeAnnotation {
+    pub generics: Arc<Vec<Arc<str>>>,
+    pub where_bounds: Arc<Vec<CalcitGenericBound>>,
+    pub arg_types: Vec<Arc<CalcitTypeAnnotation>>,
+    pub return_type: Arc<CalcitTypeAnnotation>,
+    pub fn_kind: SchemaKind,
+    pub rest_type: Option<Arc<CalcitTypeAnnotation>>,
+    /// Feature flags declared in schema, e.g. `:features $ #{} :js-ffi`
+    pub features: Arc<HashSet<EdnTag>>,
+}
+```
+
+### 3.2 `:js-object` — 类型注解
+
+在 `CalcitTypeAnnotation` 枚举中新增变体：
+
+```rust
+pub enum CalcitTypeAnnotation {
+    // ... 现有变体不变 ...
+    /// JavaScript FFI external object (opaque to Calcit type system)
+    JsObject,
+}
+```
+
+EDN 序列化：tag 名为 `:js-object`。
+
+### 3.3 Canonical Cirru EDN 形态
+
+```cirru
+%{} :CodeEntry
+  :doc "|FFI binding for DOM event handling"
+  :code $ quote
+    defn handle-click (event)
+      let
+          target $ aget event |target
+          value $ aget target |value
+        println value
+  :schema $ :: :fn
+    {}
+      :args $ [] :js-object
+      :return :unit
+      :features $ #{} :js-ffi
+```
+
+一行 Cirru EDN 示例：
+
+```cirru
+(:: :fn ({} (:args ([] :js-object)) (:return :unit) (:features (#{} :js-ffi))))
+```
+
+### 3.4 校验流程
+
+```mermaid
+flowchart TD
+    A[preprocess_expr 符号解析] --> B{调用目标是 JS FFI 函数?}
+    B -->|否| C[正常预处理]
+    B -->|是| D{当前正在编译的 def 有 :js-ffi?}
+    D -->|是| C
+    D -->|否| E[产生 Error/Warning]
+
+    F[函数 A 返回 JsObject] --> G[函数 B 接收 JsObject 作为参数]
+    G --> H{B 的 schema 有 :js-ffi?}
+    H -->|否| I[类型告警: JsObject 流入非 FFI 函数]
+    H -->|是| J[放行]
+```
+
+### 3.5 校验位置
+
+| 校验点            | 位置                                       | 触发条件                                                                            |
+| ----------------- | ------------------------------------------ | ----------------------------------------------------------------------------------- |
+| FFI 函数调用      | `preprocess_expr` → `preprocess_list_call` | head 解析为 `is_js_syntax_procs` 且当前编译上下文中 `defn` 无 `:js-ffi`             |
+| `ns js/...` 语法  | `preprocess_expr` 中 `RawCode(Js, _)` 分支 | 同上的 features 检查                                                                |
+| `JsObject` 跨边界 | `check_user_fn_arg_types`                  | 实参类型为 `JsObject` 且形参 schema 非 `JsObject` 且函数无 `:js-ffi`                |
+| `JsObject` 返回值 | `check_function_return_type`               | 返回值推断为 `JsObject` 且函数 schema 的 `:return` 非 `JsObject` 且函数无 `:js-ffi` |
+
+### 3.6 默认值与兼容
+
+- `:features` 默认 `Arc::new(HashSet::new())`，即空集合 = 无任何特殊能力
+- `:js-object` 类型的默认行为：在无 `:js-ffi` 的函数中作为 `:dynamic` 等效处理（宽松模式），或产生类型告警（严格模式）
+- 第一阶段以 **warning** 形式上线，通过 `--warn-ffi` flag 控制，后续升级为 error
+
+## 4. FFI 函数清单
+
+当前 `is_js_syntax_procs()` 收录的函数，全部受 `:js-ffi` 管控：
+
+| 函数                                    | 用途                 | 返回类型建议               |
+| --------------------------------------- | -------------------- | -------------------------- |
+| `aget` / `js-get`                       | JS 属性读取          | `:js-object` 或 `:dynamic` |
+| `aset` / `js-set`                       | JS 属性写入          | `:unit`                    |
+| `js-delete`                             | JS 属性删除          | `:unit`                    |
+| `exists?`                               | JS 属性存在性检查    | `:bool`                    |
+| `instance?`                             | JS instanceof        | `:bool`                    |
+| `&js-object`                            | 创建 JS 对象         | `:js-object`               |
+| `js-array`                              | 创建 JS 数组         | `:js-object`               |
+| `js-await` / `js-for-await`             | Promise/异步迭代     | `:js-object`               |
+| `new`                                   | JS new 构造          | `:js-object`               |
+| `set!`                                  | JS 赋值              | `:unit`                    |
+| `to-js-data`                            | Calcit → JS 转换     | `:js-object`               |
+| `to-calcit-data`                        | JS → Calcit 转换     | `:dynamic`                 |
+| `extract-cirru-edn` / `to-cirru-edn`    | EDN 序列化           | `:string` / `:dynamic`     |
+| `&raw-code`                             | 原始 JS 代码         | `:js-object`               |
+| `timeout-call`                          | 异步定时             | `:js-object`               |
+| `foldl`                                 | fold-left（JS 实现） | 依赖元素类型               |
+| `load-console-formatter!` / `printable` | 控制台输出           | `:unit`                    |
+
+> **注**：`foldl` 虽然在 JS FFI 列表中，但它是纯函数式的 fold 操作，未来可考虑移出 FFI 列表或单独归类。
+
+## 5. 实现计划
+
+### Phase 1: 数据层（~2h）
+
+- [ ] `CalcitFnTypeAnnotation.features` 字段新增
+- [ ] EDN 序列化 / 反序列化（`to_schema_edn` / `parse_loaded_schema_annotation`）
+- [ ] `CalcitTypeAnnotation::JsObject` 变体新增 + 全量 match 补齐
+- [ ] `JsObject` 的 EDN tag 解析（`:js-object`）
+
+### Phase 2: 校验层（~4h）
+
+- [ ] `preprocess_list_call` 中 FFI 调用权限校验
+- [ ] `preprocess_expr` 中 `ns js/...` 语法的 FFI 权限校验
+- [ ] 编译上下文传递：在 `ensure_ns_def_preprocessed` 链路中追踪当前 `defn` 的 features
+- [ ] `check_user_fn_arg_types` 中 `JsObject` 跨边界告警
+- [ ] `check_function_return_type` 中 `JsObject` 返回值告警
+- [ ] `--warn-ffi` CLI flag（默认开启 warning 模式）
+
+### Phase 3: 类型推断（~2h）
+
+- [ ] `&js-object`、`js-array`、`new` 等 FFI 函数的返回值推断为 `JsObject`
+- [ ] `aget` 对 `JsObject` 参数的接收校验
+- [ ] `to-calcit-data` 作为 `JsObject → Dynamic` 的转换边界
+
+### Phase 4: 迁移与测试（~3h）
+
+- [ ] 现有 `calcit/` 下使用 JS FFI 的测试文件 schema 迁移
+- [ ] 新增 `calcit/test-ffi-features.cirru` 测试用例：
+  - 无 `:js-ffi` 调用 `aget` → 预期 warning/error
+  - 有 `:js-ffi` 调用 `aget` → 预期通过
+  - 无 `:js-ffi` 接收 `JsObject` 参数 → 预期类型告警
+  - 有 `:js-ffi` 接收 `JsObject` → 预期通过
+  - `to-calcit-data` 边界转换后不再需要 `:js-ffi`
+- [ ] 文档更新（`docs/features.md`）
+
+### Phase 5: 严格模式（后续版本）
+
+- [ ] 缺少 `:js-ffi` 的 FFI 调用从 warning 升级为 hard error
+- [ ] `:js-object` 可能扩展到区分 `:js-object` vs `:js-array` vs `:js-promise`
+
+## 6. 风险与缓解
+
+| 风险                                    | 影响               | 缓解                                                 |
+| --------------------------------------- | ------------------ | ---------------------------------------------------- |
+| 现有 Cirru 代码大量使用 FFI 但无 schema | 迁移工作量大       | 先 warning 后 error；提供迁移脚本                    |
+| `foldl` 列入 FFI 引起误报               | 纯函数被标记为 FFI | 考虑将 `foldl` 移出 `is_js_syntax_procs` 或单独分类  |
+| 宏生成的函数自动获取 `:js-ffi`          | 权限继承不明确     | 宏生成函数的 features 从宏定义处显式声明，不自动继承 |
+| 第三方库适配周期长                      | 生态断裂           | 预留至少一个大版本的 warning-only 过渡期             |
+
+## 7. 未来扩展
+
+`:features` 设计为 `HashSet<EdnTag>`，天然支持未来新增能力标记：
+
+| 标记            | 含义                                             |
+| --------------- | ------------------------------------------------ |
+| `:js-ffi`       | 可使用 JS interop 语法（本次实现）               |
+| `:side-effects` | 函数可能产生副作用（未来：配合 effects graph）   |
+| `:async`        | 函数内部使用异步操作（未来：配合 effect 系统）   |
+| `:unsafe`       | 函数绕过了类型检查（未来：配合 unsafe block）    |
+| `:host`         | 函数需要宿主环境 API（未来：配合多 target 编译） |
+
+## 8. 参考资料
+
+- 现有 JS FFI 函数定义：`src/builtins.rs:649` `is_js_syntax_procs()`
+- 现有 Schema 结构：`src/calcit/type_annotation.rs:3826` `CalcitFnTypeAnnotation`
+- 现有预处理入口：`src/runner/preprocess/mod.rs` `preprocess_expr()`
+- 相关 RFC：[Type Slot 机制](./04-13-type-slot-mechanism-rfc.md)、[泛型 `:where` 约束](./05-31-generic-where-bounds-mfs.md)

package/RFCs/07-19-doc-knowledge-index-rfc.md

@@ -0,0 +1,195 @@
+# RFC: 文档知识节点与增量关系索引
+
+状态：Draft  
+日期：2026-07-19  
+关联：`docs/docs-indexing.md`、`07-06-semantic-tree-navigation-rfc.md`
+
+## 1. 概要
+
+在保持 Markdown 可读、可 Git 管理的前提下，为 `cr docs` 增加一层结构化的文档知识索引：
+
+```text
+Markdown / Calcit snapshot
+        ↓
+文档节点与关系解析
+        ↓
+~/.config/calcit/docs-cache/
+        ↓
+搜索、跳转、LLM context、缺失检查
+```
+
+Markdown 和 Calcit 源码仍然是事实来源；缓存只是可以删除并重新生成的派生数据。
+
+## 2. 目标
+
+1. 文档可以表达稳定的知识节点，而不要求一次性拆分所有 Markdown。
+2. 通过 `id`、`parent`、`related`、`requires`、`leads_to` 组织树与图关系。
+3. 通过 `namespace/definition` 将文档节点关联到真实 Calcit 定义。
+4. 使用用户级 JSON 文本缓存，不引入 SQLite 或其他二进制数据库。
+5. 文件内容变化时增量失效；解析器或 schema 变化时全量失效。
+6. 能发现孤立节点、断链、未文档化定义和缺少必要章节。
+
+## 3. 非目标
+
+- 当前不引入 RDF、SPARQL、Neo4j 或 SurrealDB。
+- 当前不强制把每个章节拆成独立文件。
+- 当前不把缓存当作用户需要手工维护的知识源。
+- 当前不改变既有 `cr docs search/read` 的默认输出语义。
+
+## 4. 文档元数据
+
+现有字段继续保留：`title`、`summary`、`scope`、`kind`、`category`、`aliases`、`entry_for`。
+
+新增字段采用稳定 ID 和关系字段：
+
+```yaml
+id: api/list/nth
+code_refs:
+  - calcit.core/nth
+parent: structure/list
+related:
+  - api/list/get
+requires:
+  - concept/indexing
+leads_to:
+  - example/list-access
+```
+
+实现阶段允许使用 `x-calcit` / `extensions` 命名空间保存项目专属字段，避免污染通用 frontmatter。
+
+`id` 是语义身份；`namespace/definition` 只是代码引用，不能互相替代。
+
+## 5. 缓存模型
+
+默认位置：
+
+```text
+~/.config/calcit/docs-cache/v1/<project-id>/
+```
+
+项目身份至少包含项目根目录，避免不同项目的相对路径发生冲突。缓存还记录解析器/schema 版本和内置 Calcit core snapshot 的定义指纹；任一输入变化都会触发重建。
+
+缓存由两部分组成：
+
+```json
+{
+  "nodes": [],
+  "edges": []
+}
+```
+
+每个文件还需要记录：
+
+```json
+{
+  "path": "docs/structures/list.md",
+  "content_hash": "...",
+  "parser_version": 1,
+  "schema_version": 1,
+  "node_ids": ["structure/list"]
+}
+```
+
+内容 hash 不变时可以复用文件级解析结果；parser/schema 版本变化时必须重新解析。
+
+## 6. 关系模型
+
+树关系：
+
+- `parent`
+- `contains`
+- `leads_to`
+
+语义关系：
+
+- `related`
+- `requires`
+- `documents`
+- `implements`
+- `example_of`
+
+节点采用树形入口，关系采用独立边表，避免把循环关系硬塞进嵌套结构。
+
+## 7. 分阶段计划
+
+### Phase A：元数据兼容与增量缓存基础
+
+- 扩展 frontmatter 解析器，保留未知扩展字段的兼容空间；
+- 定义节点、边、文件缓存的 JSON schema；
+- 增加内容 hash、parser version、schema version；
+- 保持现有搜索和读取命令兼容；
+- 添加解析和失效测试。
+
+### Phase B：导航查询
+
+已完成第一版面向知识节点的查询：
+
+```bash
+cr docs graph build
+cr docs graph check
+cr docs graph children <node>
+cr docs graph related <node>
+cr docs graph path <from> <to>
+```
+
+查询当前从 Markdown 构建 JSON cache，并通过双向 BFS 查找关系路径：
+
+```bash
+cr docs graph path core/features/list core/run/edit-tree
+# core/features/list -> core/run/query -> core/run/edit-tree
+```
+
+当前已支持通过 `code_refs` 反查关联文档节点；后续再增加源码定义、示例和正文聚合：
+
+```bash
+cr docs graph explain <definition>
+```
+
+### Phase C：完整性检查
+
+```bash
+cr docs graph check
+cr docs graph orphans
+cr docs graph missing
+```
+
+检查断链、孤立节点、无正文定义、缺少示例和缺少必要章节。
+
+当前已实现：
+
+- `cr docs graph check`：检查关系边是否指向已知文档节点；
+- `cr docs graph missing [--ns <prefix>] [--limit <n>]`：按 namespace 分批检查带有 snapshot 文档说明、但没有 `code_refs` 的定义；
+- `cr docs graph orphans`：检查没有任何关系的文档节点。
+
+## 8. 验证标准
+
+- 删除缓存后，查询结果与重新构建结果一致；
+- 只修改一个 Markdown 文件时，不重新解析其他未变化文件；
+- 修改 parser/schema 版本时会全量失效；
+- 不带新增元数据的旧 Markdown 行为保持不变；
+- 缓存只包含 JSON/文本，不提交到 Git；
+- `cargo fmt`、`cargo clippy -- -D warnings`、`cargo test` 通过。
+
+### 当前验证矩阵
+
+Phase A 当前已验证：
+
+| 案例 | 结果 |
+| --- | --- |
+| 没有 frontmatter 的旧文档 | 保持空知识元数据，不影响旧搜索 |
+| 只有 `id` / `parent` | 正确解析树入口 |
+| 单值和多值关系混用 | 保持声明顺序并正确合并 |
+| `related` / `requires` / `leads_to` 交叉关系 | 可表达树外关系 |
+| 旧的 `title` / `aliases` / `entry_for` | 不会误解析为知识关系 |
+| 未闭合 frontmatter | 丢弃知识元数据，避免部分解析污染索引 |
+| 文件内容变化 | 内容 hash 失效 |
+| parser/schema 版本变化 | 缓存失效 |
+| `code_refs` 反查 definition | 返回关联文档节点 |
+| 不同项目根目录 | 缓存路径隔离 |
+| nodes/edges/files JSON 往返 | 保持结构和关系信息 |
+
+当前仍未接入的能力：
+
+- 从 Calcit snapshot 自动生成 `code_refs`（当前已加载内置 core snapshot，并校验引用是否可解析；应用/模块 snapshot 仍未接入）；
+- 自动根据 definition 的 `:examples` 检查文档示例覆盖；
+- 从 graph 节点聚合正文、schema、examples 的 LLM context。

package/RFCs/07-19-type-introspection-consistency-rfc.md

@@ -0,0 +1,73 @@
+# RFC: 类型自省(Type Introspection)一致性改进
+
+状态：Implemented（1-3 项已落地，第 4 项按计划延后）
+日期：2026-07-19
+
+---
+
+## 1. 概要
+
+调研 Calcit 当前"查询一个类型能怎么交互"的能力——有哪些字段、有哪些方法(无论是内建还是通过 trait/impl 附加的)——发现相关能力**分散在多个不对齐的 API 里**，且存在几处"数据已经在运行时结构里，但没有暴露给 Calcit 代码"的具体 gap。本 RFC 记录调研结论，并给出可落地的修复项清单。
+
+## 2. 调研结论
+
+### 2.1 方法(methods)查询——统一性最好的部分
+
+`&methods-of` / `&inspect-methods`([meta.rs](../src/builtins/meta.rs))把"内建方法"(list/map/string/number/set/fn 各自的 `&core-*-impls`)和"用户 `defimpl`/`impl-traits`"统一表示成 `CalcitImpl`，按优先级顺序去重合并，`&methods-of` 对内建/自定义一视同仁。
+
+局限：`collect_impl_records_for_value` 只接受**实例值**(`Tuple`/`Record`/`List`/`Map`/`Number`/`Str`/`Set`/`Fn`/`Proc`)，不接受裸的 `Calcit::Struct`/`Calcit::Enum`/`Calcit::Trait`(类型定义本身)。也就是说 `&methods-of Person`(还没造实例)会直接报错，必须先构造一个实例才能查询"这个类型将来会有哪些方法"。
+
+`NativeMethodsOf` 的类型签名是 `arg_types: vec![dynamic_tag()]`（[proc_name.rs](../src/calcit/proc_name.rs)），说明这一限制纯粹是**运行时实现**的限制，不是类型检查器强加的——修复它不需要碰类型系统。
+
+### 2.2 字段(fields)查询——能用，但类型签名与实现脱节
+
+`to-pairs`/`keys`/`&record:to-map` 在运行时(`to_pairs` in [maps.rs](../src/builtins/maps.rs))原生支持 `Calcit::Record`，能拿到字段名（tag）。
+
+但 `ToPairs` 的类型签名声明 `arg_types: vec![some_tag("map")]`，而 `matches_with_bindings`([type_annotation.rs](../src/calcit/type_annotation.rs))里 `(TypeRef("map"), Record(base))` 这一分支是拿 `"map"` 去匹配 `base.name`（即结构体自己的名字，比如 `"Person"`），显然不相等 → **对 record 调用 `to-pairs`/`keys` 会在类型检查阶段被判定为类型不匹配并产生告警**，即便运行时完全正确。这是文档/类型签名与实际能力脱节的具体例子。
+
+没有实例、只有裸类型定义时（刚 `defstruct Person ...` 还没构造实例），**没有**可编程 API 能拿到字段名列表当数据用；唯一能看到字段的方式是 `println`/`str` 对 struct 值做格式化输出人肉读。
+
+### 2.3 `Display`（`println`/`str`）在三种类型定义值之间不对称
+
+`impl fmt::Display for Calcit`（[calcit.rs](../src/calcit.rs)）：
+
+| 类型定义值 | 输出示例 | 包含信息 |
+| --- | --- | --- |
+| `Struct` | `(%struct :Person (:name string) (:age number))` | 字段名 + 类型 |
+| `Trait` | `(trait Name :m1 :m2)` | 仅方法名，**没有**方法签名类型 |
+| `Enum` | `(%enum :Name)` | **仅名字**，连 variant 列表都没有 |
+
+`CalcitEnum` 内部其实完整保存着 `variants()`（tag + payload_types，见 [sum_type.rs](../src/calcit/sum_type.rs)），数据都在，只是没接到 `Display` 里——这是一处"能力已具备却未暴露"的明显 gap，且没有任何测试覆盖这个输出格式（`grep "%struct"`/`"%enum"` 在 `calcit/*.cirru` 测试里零命中）。
+
+### 2.4 结论
+
+- 没有一个统一的"describe 类型"入口能同时列出 fields + methods（不管来源）；需要组合调用不同风格的 API。
+- 对"类型定义本身"（还未实例化）的支持最弱：`&methods-of` 不接受、字段列表没有编程接口、`Enum`/`Trait` 的打印格式也比 `Struct` 缺信息。
+
+## 3. 修复计划(按优先级/风险排序)
+
+1. ✅ **`Enum` 的 `Display` 补上 variants**（最小、最安全，纯展示层修复，无 API 变化）。
+   - 实现：[src/calcit.rs](../src/calcit.rs) `impl fmt::Display for Calcit` 的 `Enum` 分支，现在遍历 `enum_def.variants()` 输出 `(:tag type1 type2 ...)`。
+   - 测试：`enum_display_includes_variants`（同文件 `#[cfg(test)] mod tests`）。
+2. ✅ **`&methods-of` 接受裸 `Struct`/`Enum`/`Trait` 值**（直接读它们自带的 `impls` 字段），不再强制要求实例。
+   - 实现：[src/builtins/meta.rs](../src/builtins/meta.rs) `collect_impl_records_for_value` 新增 `Struct`/`Enum` 分支；`iter_impls_in_precedence_order` 把 `Struct`/`Enum` 纳入与 `Tuple`/`Record` 相同的“后定义优先”倒序规则；`Trait` 单独处理（直接读 `trait_def.methods`，因为 trait 本身没有 `impls` 字段，是直接声明方法名）。`methods_of`/`inspect_methods` 都做了对应分支。
+   - JS 同步：[ts-src/calcit.procs.mts](../ts-src/calcit.procs.mts) 的 `lookup_impls`/`_$n_methods_of`/`_$n_inspect_methods` 同步补齐 `CalcitStruct`/`CalcitEnum`/`CalcitTrait` 分支。
+   - 测试：[calcit/test-traits.cirru](../calcit/test-traits.cirru) 的 `test-method-introspection` 新增对 `impl-traits Person0 MyFooImpl`（裸 struct）、`DemoBar`（裸 enum）、`MyFoo`（裸 trait）调用 `&methods-of` 的断言，`yarn check-all`（rs/js/ir/wasm 四目标）全部通过。
+3. ✅ **修正 `to-pairs`/`keys` 的类型签名**，让 record 也能匹配，消除虚假类型告警。
+   - 实现：[src/calcit/type_annotation.rs](../src/calcit/type_annotation.rs) `matches_with_bindings` 里 `(TypeRef, Record)` 分支新增：当 `TypeRef` 名字就是泛化的 `"map"` 时，结构性地匹配任意 record（不要求 record 名字等于 `"map"`）。
+   - 测试：新增单元测试 `generic_map_type_ref_accepts_records_structurally`，直接验证 `TypeRef("map")` 与 `Record(Person)` 现在双向匹配，同时确认无关的 `TypeRef` 名字仍然不会误匹配。
+   - 备注：实测 `cr --check-only` 在当前仓库测试集里并未因这个 gap 产生可观察的告警（`test-record.cirru` 里 `keys p2` 这行本来就没有触发过告警，猜测是这条路径上的静态类型推断没有把 `p2` 识别为具体的 `Record` 类型，所以没有触发 `check_proc_arg_types` 这条检查分支）。但 `matches_with_bindings` 的错误比较逻辑本身是真实存在的 bug，属于防御性修复：一旦未来静态推断能力增强（例如给变量加显式类型标注后传入 `to-pairs`/`keys`），就不会再误报。
+4. ⏸️ **（可选，视时间，本轮未实现）** 新增 `&struct:fields`/`&enum:variants` 之类的编程接口，让“裸类型定义”的字段/variant 列表也能被程序消费，而不仅仅是打印文本。
+   - 未实现原因：新增一个 proc 需要贯穿 `proc_name.rs`(注册+类型签名)、`builtins.rs`(分发)、`builtins/records.rs`或`meta.rs`(实现)、以及 JS/IR/WASM 三个 codegen 目标的同步实现，工作量与收益相比前三项更低（前三项已经解决了运行时能力不对齐的核心问题；字段/variant 名字目前仍可通过 `Display`/`println` 人肉获取，只是没有编程接口）。留作后续独立迭代。
+
+## 4. 兼容性 / 风险
+
+- 第 1、2、3 项都已实现并通过 `cargo test`、`cargo run --bin cr -- calcit/test.cirru`、`yarn check-all`、`cargo clippy -- -D warnings`、`cargo fmt` 验证，纯粹的能力扩展/告警范围放宽，不改变现有行为，向后兼容。
+- 第 4 项延后，不影响现有行为。
+
+## 5. 验证方式（已执行）
+
+- `cargo test`：新增/更新的 Rust 单元测试全部通过，覆盖 `Display for Enum`、`&methods-of` 对裸类型定义的调用、`to-pairs`/`keys` 的类型匹配放宽。
+- `cargo run --bin cr -- calcit/test.cirru`：Cirru 集成测试套件全部通过，包括新增的裸类型 `&methods-of` 断言。
+- `yarn check-all`：JS/IR/WASM 三个目标同步验证通过（`&methods-of` 的 JS 实现已同步补齐）。
+- `cargo clippy -- -D warnings` / `cargo fmt`：均无告警。

package/RFCs/README.md

@@ -29,6 +29,9 @@
 | `05-31-generic-where-bounds-mfs.md`                 | Active        | 函数 schema 泛型 `:where` 约束的最小功能规格，先作为主链路开发基线。                      |
 | `06-15-effects-graph-rfc.md`                        | Draft         | `cr analyze effects-graph`：State/Transform/Effect 语义分解图与类型驱动 effect 标注路线。 |
 | `06-29-cr-exec-cli-builtins-rfc.md`                 | **Active**    | `cr exec` + `calcit.cli/*` 内建函数：绕过 Shell 转义的 Cirru 函数调用方案。               |
+| `07-06-semantic-tree-navigation-rfc.md`             | Draft         | 语义化树形导航与编辑：路径标注、多候选交互、锚点搜索替换、结构化查询语言。                |
+| `07-19-doc-knowledge-index-rfc.md`                  | Draft         | Markdown/Calcit snapshot 的知识节点、关系索引与用户级增量缓存方案。                       |
+| `07-19-type-introspection-consistency-rfc.md`       | Implemented   | 类型自省一致性改进：`&methods-of` 支持裸类型定义、`Enum` Display 补 variants、`to-pairs`/`keys` 类型签名修正（第 4 项可选新增 proc 延后）。 |
 
 ## 已执行的清理
 

package/build.rs

@@ -305,10 +305,8 @@ fn parse_code_entry(edn: Edn, owner: &str) -> Result<CodeEntry, String> {
       "examples" => examples = from_edn(value.clone()).map_err(|e| format!("{owner}: invalid `:examples`: {e}"))?,
       "tags" => tags = parse_tags_from_edn(value, owner)?,
       "code" => code = Some(from_edn(value.clone()).map_err(|e| format!("{owner}: invalid `:code`: {e}"))?),
-      "schema" => {
-        if !matches!(value, Edn::Nil) {
-          schema = Some(parse_schema_from_edn(value, owner).map_err(|e| format!("{owner}: invalid `:schema`: {e}"))?);
-        }
+      "schema" if !matches!(value, Edn::Nil) => {
+        schema = Some(parse_schema_from_edn(value, owner).map_err(|e| format!("{owner}: invalid `:schema`: {e}"))?);
       }
       _ => {}
     }

package/editing-history/2026-04-07-1550-path-format-at-prefix-migration.md

@@ -0,0 +1,40 @@
+## Path format migration: `@` prefix for display paths
+
+### What changed
+
+All display-level Cirru tree paths now use `@` prefix notation when rendered to user.
+
+### Display format change
+- `1.2.3.4` → `@1.2.3.4` (bare path)
+- `[1.2.3.4]` → `[@1.2.3.4]` (bracketed path)
+- `NodeLocation::Display` now outputs `ns/def [@1.2.3]` instead of `ns/def [1.2.3]`
+
+### Backward compatibility
+- `parse_path()` strips leading `@` if present, so CLI input still accepts both `@1.2.3` and `1.2.3`
+- Error messages and help text updated to show `@` format
+
+### Files modified
+
+**Core functions:**
+- `src/bin/cli_handlers/common.rs`: `format_path()` returns `@1.2.3`; `parse_path()` strips `@` prefix; test assertions updated
+- `src/calcit.rs`: `NodeLocation::Display` outputs `[@1.2.3]`; test assertion updated
+- `src/bin/cli_handlers/cirru_validator.rs`: local `format_path()` updated
+- `src/type_coverage.rs`: `format_cirru_path()` updated
+- `src/bin/cli_handlers/chunk_display.rs`: `compare_coords()` strips `@`; test `fragment()` helper uses `@`
+- `src/runner/preprocess/mod.rs`: `[&inspect-type]` debug output uses `@`
+
+**Tree/edit handlers:**
+- `src/bin/cli_handlers/tree.rs`: inline path formatting in swap handler
+- `src/bin/cli_handlers/edit.rs`: error message example
+- `src/cli_args.rs`: help text examples (3 locations)
+
+**Documentation:**
+- `docs/CalcitAgent.md`: 19 path examples updated
+- `docs/run/agent-advanced.md`: 23 path examples updated
+- `docs/run/edit-tree.md`: 6 path examples updated
+- `docs/Respo-Agent.md` (respo project): 26 path examples updated
+
+### Why
+- `@` prefix helps LLMs distinguish path coordinates from other dotted numeric patterns (like version numbers or floats)
+- `@` is safe in shell (no escaping needed)
+- All display output now consistent with `@` prefix

package/editing-history/2026-07-07-0000-semantic-tree-navigation.md

@@ -0,0 +1,54 @@
+# 语义化树形导航实现 (2026-07-07)
+
+## 变更概要
+
+实现 RFC `07-06-semantic-tree-navigation-rfc.md` 全部四个 Phase。
+
+## 实现功能
+
+### L1: `--path-annotations`
+
+- `cr tree show` 新增 `--path-annotations` flag
+- 开启后递归为所有嵌套 `Cirru::List` 末尾追加 `; "previous node path: X.Y.Z"` 注释节点
+- AST 层面操作：`children.push(Cirru::List([Cirru::Leaf(";"), Cirru::Leaf(path_string)]))`
+- 子节点 > 8 时底部 tip 提示可开启
+
+### L2: `--pick` 多候选选择
+
+- `search-replace` 多匹配时展示带路径、上下文的候选列表
+- `--pick <N>` 直接选择第 N 个候选执行替换
+
+### L4: 语义路径表达式
+
+- `cr query path <ns> --selector 'path heading ... nth ...'`
+- 三个选择器：裸叶子（精确匹配）、`heading`（前缀匹配）、`nth`（位置导航）
+- `resolve_path_expression` 函数解析并返回数字路径
+
+### L4: `--selector` 限定搜索范围
+
+- `search-replace --selector 'path ...'` 在语义路径定位的子树内搜索替换
+- 与 `cr query path` 共用同一套选择器语法
+
+### Phase 4: `cr query anchors`
+
+- 遍历 AST 中 `noted @anchor:<name>` 调用，输出锚点名称和路径
+
+## 修改文件
+
+| 文件                                         | 变更                                                                                                               |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `src/cli_args.rs`                            | 新增 `path_annotations`, `pick`, `selector` 字段；新增 `QueryPathCommand`, `QueryAnchorsCommand`                   |
+| `src/bin/cli_handlers/tree.rs`               | `annotate_paths` 函数；`handle_show` 路径标注 + tip；`handle_search_replace` 多候选 + selector                     |
+| `src/bin/cli_handlers/query.rs`              | `resolve_path_expression`(pub), `starts_with_pattern`, `handle_query_path`, `handle_query_anchors`, `find_anchors` |
+| `src/bin/cli_handlers/command_echo.rs`       | Path/Anchors 子命令 echo 支持                                                                                      |
+| `docs/CalcitAgent.md`                        | 精简引用新功能                                                                                                     |
+| `docs/run/agent-advanced.md`                 | 详细示例文档                                                                                                       |
+| `RFCs/07-06-semantic-tree-navigation-rfc.md` | 新增 RFC                                                                                                           |
+
+## 设计决策
+
+- `--at`/`--child` 链式语法被 `--selector` 替代，代码中已移除
+- `exact` 选择器不纳入——链式导航模型不需要独立精确匹配，`heading` 无多余子节点时等同
+- `sub-path` 选择器不纳入——L1 路径标注让 `nth` 足够
+- 路径注释放在 list 末尾（不破坏已有子节点索引）
+- `Cirru::Leaf` 存原始内容，格式化时自动加引号

package/editing-history/2026-07-08-1650-features-and-js-object-type.md

@@ -0,0 +1,27 @@
+# `:features` function schema + `:js-object` type + CLI simplification
+
+## Changes
+
+### Feature: `:features` and `:js-object` type system
+
+- Added `features: Arc<HashSet<EdnTag>>` to `CalcitFnTypeAnnotation` for marking function capabilities
+- Added `CalcitTypeAnnotation::JsObject` variant for opaque JS FFI data
+- EDN round-trip for both (`features_to_edn` + `parse_fn_features_from_form`)
+- Manually implemented `PartialOrd`/`Ord`/`Hash` for `CalcitFnTypeAnnotation`
+- `CURRENT_FN_FEATURES` thread-local + `lookup_def_schema` fallback for FFI checking
+- `as_fn()` helper on `CalcitTypeAnnotation`
+- `#{}` hashset support in `schema_cirru_to_edn`
+- `:features` field validation in `validate_schema_for_write`
+- All direct FFI callers marked with `:features $ #{} :js-ffi`
+
+### Refactor: CLI simplification
+
+- Removed `--json` option and `--json-input` switch from all edit/tree subcommands
+- Auto-detect JSON (`[` prefix) vs Cirru EDN (`quote` prefix) in `parse_input_to_cirru`
+- Simplified `read_code_input` to `(file, code)` params; stdin fallback
+- Removed `json()`/`json_input()` from `InsertOperation` trait
+- Simplified `CodeInputParts` to only carry `file`+`code`
+- Added stdin mention to all edit subcommand help texts
+- Updated agent docs (CalcitAgent.md, agent-advanced.md, cirru-syntax.md, edit-tree.md)
+- Cleaned up stale short flag mentions (`-j`, `-J`, `-e`)
+- Changed js-interop doc blocks to `no-check` to avoid FFI warnings

package/editing-history/2026-07-09-1700-concise-method-representation.md

@@ -0,0 +1,8 @@
+# Edit History - Concise Method Representation and Introspection Refactoring
+
+- **Objective**: Improve the representation of methods inside the VM to return first-class `Calcit::Method` values rather than strings from `&methods-of`, and provide a concise, user-facing rendering suitable for REPL and dynamic inspection rather than verbose list expressions, all while keeping internal preprocessing unaffected.
+- **Actions**:
+  - Refactored `methods_of` in `src/builtins/meta.rs` to return native `Calcit::Method` values directly with leading dots stripped.
+  - Implemented custom `turn_string` in `src/calcit.rs` for `Calcit::Method` to format method values concisely (e.g., `.add`, `.-field`, `.!native`) for `str` conversions, prints, and dynamic assertions.
+  - Updated `format_to_lisp` in `src/calcit.rs` to keep `format_to_lisp` compatible with internal macros (like `deftrait` which dynamically slices `format-to-lisp` output starting from the 9th character).
+  - Cleaned up assertions inside `calcit/test-traits.cirru`'s `test-method-introspection` to map `&methods-of` outputs to string using `str` rather than raw assertion of methods list, ensuring absolute compatibility and safety.