@calcit/procs 0.12.47 → 0.12.49

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/README.md

@@ -1,6 +1,6 @@
 # RFC 整理索引
 
-更新时间：2026-06-15
+更新时间：2026-06-29
 
 ## 目录原则
 
@@ -10,24 +10,26 @@
 
 ## 当前保留文件
 
-| 文件                                | 状态          | 建议                                                       |
-| ----------------------------------- | ------------- | ---------------------------------------------------------- |
-| `03-05-function-schema-dual-track-rfc.md` | Active        | 已收敛为当前 schema 约定说明，涉及函数 schema 时优先参考。 |
-| `02-04-runtime-traits-plan.md`            | Active        | runtime traits 主设计文档。                                |
-| `02-17-register-platform-api-rfc.md`      | Active        | host capability / register API 规范草案。                  |
-| `02-18-language-theory-evolution-plan.md` | Review-needed | 偏理论路线图，阅读时需区分愿景与已落地内容。               |
-| `02-23-optional-record-macro-plan.md`     | Review-needed | 小范围提案，尚未进入稳定实现。                             |
-| `02-14-project-modernization-roadmap.md`  | Review-needed | 工程路线图可参考，但不要当作语法或行为文档。               |
-| `03-16-runtime-boundary-refactor-plan.md` | Review-needed | 运行时边界重构方案。 |
-| `03-18-query-def-tree-show-chunked-display-plan.md` | Review-needed | query/tree show 分块展示方案。 |
-| `04-13-call-arg-literal-rewrite-rfc.md` | Active | 调用参数字面量重写优化提案。 |
-| `04-13-type-slot-mechanism-rfc.md` | Active | Type slot 机制提案。 |
-| `04-15-match-syntax-rfc.md` | Active | match 语法改进提案。 |
-| `04-15-type-directed-optimization-catalog.md` | Active | 基于 `&record:nth` 经验，系统梳理 Record/Tuple/Scope 等类型导向优化机会。 |
-| `04-15-wasm-compilation-feasibility.md` | Active | WASM 编译三条路径（解释器→WASM / AOT 子集 / WASM GC）的可行性评估。 |
-| `04-16-wasm-data-structures.md` | Active | WASM codegen 中 Tag/Record/Tuple 等数据结构的内存布局与编译策略。 |
-| `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 标注路线。 |
+| 文件                                                | 状态          | 建议                                                                                      |
+| --------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------- |
+| `03-05-function-schema-dual-track-rfc.md`           | Active        | 已收敛为当前 schema 约定说明，涉及函数 schema 时优先参考。                                |
+| `02-04-runtime-traits-plan.md`                      | Active        | runtime traits 主设计文档。                                                               |
+| `02-17-register-platform-api-rfc.md`                | Active        | host capability / register API 规范草案。                                                 |
+| `02-18-language-theory-evolution-plan.md`           | Review-needed | 偏理论路线图，阅读时需区分愿景与已落地内容。                                              |
+| `02-23-optional-record-macro-plan.md`               | Review-needed | 小范围提案，尚未进入稳定实现。                                                            |
+| `02-14-project-modernization-roadmap.md`            | Review-needed | 工程路线图可参考，但不要当作语法或行为文档。                                              |
+| `03-16-runtime-boundary-refactor-plan.md`           | Review-needed | 运行时边界重构方案。                                                                      |
+| `03-18-query-def-tree-show-chunked-display-plan.md` | Review-needed | query/tree show 分块展示方案。                                                            |
+| `04-13-call-arg-literal-rewrite-rfc.md`             | Active        | 调用参数字面量重写优化提案。                                                              |
+| `04-13-type-slot-mechanism-rfc.md`                  | Active        | Type slot 机制提案。                                                                      |
+| `04-15-match-syntax-rfc.md`                         | Active        | match 语法改进提案。                                                                      |
+| `04-15-type-directed-optimization-catalog.md`       | Active        | 基于 `&record:nth` 经验，系统梳理 Record/Tuple/Scope 等类型导向优化机会。                 |
+| `04-15-wasm-compilation-feasibility.md`             | Active        | WASM 编译三条路径（解释器→WASM / AOT 子集 / WASM GC）的可行性评估。                       |
+| `04-16-wasm-data-structures.md`                     | Active        | WASM codegen 中 Tag/Record/Tuple 等数据结构的内存布局与编译策略。                         |
+| `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         | 语义化树形导航与编辑：路径标注、多候选交互、锚点搜索替换、结构化查询语言。                |
 
 ## 已执行的清理
 

package/editing-history/2026-06-27-0052-cli-improvements.md

@@ -0,0 +1,41 @@
+## CLI 改进: target-replace → search-replace, 新增 batch-delete, --parent-path
+
+### 改动机
+根据 pudica-schedule-viewer 升级过程中暴露的多次 cr 命令使用痛点:
+
+1. `target-replace` 命名不直观（"目标替换"不如"搜索替换"清晰）
+2. 连续删除多个属性时需要手动从高到低删除，容易出错
+3. 搜索结果的路径是叶子路径，用户需要手动去掉末尾索引得到可编辑父路径
+4. map 属性中用 `$` 编辑的规则未在文档中明确
+
+### 改动清单
+
+**src/cli_args.rs:**
+- `TargetReplace(TreeTargetReplaceCommand)` → `SearchReplace(TreeSearchReplaceCommand)`
+- `#[argh(subcommand, name = "target-replace")]` → `#[argh(subcommand, name = "search-replace")]`
+- 新增 `BatchDelete(TreeBatchDeleteCommand)` 枚举变体
+- 新增 `TreeBatchDeleteCommand` 结构体（`-p` 接受多个路径）
+- `QuerySearchCommand` 新增 `--parent-path` 开关
+
+**src/bin/cli_handlers/tree.rs:**
+- `handle_target_replace` → `handle_search_replace`
+- 新增 `handle_batch_delete`: 按路径降序依次调用 `handle_delete`
+
+**src/bin/cli_handlers/query.rs:**
+- `SearchCommonOpts` 新增 `parent_path: bool` 字段
+- 搜索结果中 `--parent-path` 开启时额外打印父路径
+
+**src/bin/cli_handlers/command_echo.rs:**
+- 更新所有 `TargetReplace` → `SearchReplace` 分发
+- 新增 `BatchDelete` 的三个 match arm
+
+**src/bin/cli_handlers/edit.rs:**
+- 错误提示 `target-replace` → `search-replace`
+
+**src/bin/cli_handlers/docs_tests.rs:**
+- 测试数据中 `target-replace` → `search-replace`
+
+**docs/CalcitAgent.md + 其他文档:**
+- 所有 `target-replace` 替换为 `search-replace`
+- 新增 `batch-delete` 和 `--parent-path` 用法说明
+- 新增 `$` 在属性 map 中的编辑指南

package/editing-history/2026-06-27-0202-docs-indexing-improvements.md

@@ -0,0 +1,22 @@
+## 文档索引改进: abstract 字段 + --summary 模式 + Hub 标记
+
+### 改动内容
+
+**P0: abstract/summary 字段**
+- `GuideDocFrontmatter` 新增 `summary: Option<String>` 字段
+- `parse_doc_frontmatter` 支持解析 `summary:` 键值对
+- `score_metadata_hit` 加入 summary 评分（exact 200，contains 130）
+- 8 个核心文档已添加 summary 描述
+
+**P0: `cr docs search --summary` 模式**
+- `DocsSearchCommand` 新增 `--summary` 开关
+- 搜索时只显示文档标题 + summary，不输出内容片段
+- 无 summary 的文档显示 `(no summary)`
+
+**P0: Hub 标记**
+- 搜索结果中 `kind: hub` 的文档显示 `[Hub]` 前缀
+- 帮助 LLM 快速识别导航页 vs 详细页
+
+**文档更新**
+- `docs-indexing.md` 新增 `summary` 字段规范说明和 `--summary` 用法
+- `docs-validation.md` 新增 `--summary` 和 hub 标记的验证用例

package/editing-history/2026-06-27-0315-file-splits.md

@@ -0,0 +1,17 @@
+## 文档拆分: agent-advanced.md 和 CalcitAgent.md 的部分内容拆成独立文件
+
+### 改动内容
+
+**从 `run/agent-advanced.md` 拆分:**
+- `## 快速开始` 节 (原 lines 24-58) → 新建 `run/quick-start.md` (47行)
+- 原文替换为交叉链接
+
+**从 `CalcitAgent.md` 拆分:**
+- `calcit.cirru EDN 结构` + `deps.cirru` 两节 (原 lines 156-231) → 新建 `run/project-structure.md` (82行)
+- `结构化策略（5 招）` 节 → 新建 `run/structural-strategies.md` (53行)
+- 原文替换为交叉链接
+
+### 新文件
+- `docs/run/quick-start.md` — 新 LLM 快速开始工作流
+- `docs/run/project-structure.md` — calcit.cirru EDN 结构 + deps.cirru
+- `docs/run/structural-strategies.md` — cp/mv/wrap/raise/rewrite 策略

package/editing-history/2026-06-27-0416-agent-advanced-split.md

@@ -0,0 +1,15 @@
+## agent-advanced.md 拆分: CLI 命令和语言基础节替换为交叉链接, 开发调试拆出独立文件
+
+### 改动
+
+**`run/agent-advanced.md` 精简 (1598→807 行, ~49%):**
+
+- `## Calcit CLI 命令` 节 (~508行): 替换为独立文件链接列表，保留 `LLM 辅助：动态方法提示` 和 `复杂表达式分段组装策略` 两个独特子节
+- `## Calcit 语言基础` 节 (~266行): 替换为 cirru-syntax.md / features/tuples.md / features/static-analysis.md 链接，保留 `其他易错点`
+- `## 开发调试` 节 (~99行): 拆出为独立 `run/debugging.md`
+
+**新增文件:**
+- `run/debugging.md` — watcher 监听模式、增量更新、编译检查
+
+### 删除的重复内容
+CLI 命令和语言基础的子节内容在 `run/query.md`、`run/edit-tree.md`、`cirru-syntax.md`、`features/static-analysis.md` 等文件中已有完整覆盖。

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

@@ -0,0 +1,49 @@
+# 语义化树形导航实现 (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,25 @@
+# `: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/202607040040-fix-format-cirru-edn-quoting.md

@@ -0,0 +1,14 @@
+## fix format-cirru-edn missing quotes for strings with spaces in JS codegen
+
+### 问题
+`format-cirru-edn` 在 JS runtime 中对含空格的字符串（如 `"a b"`）输出缺少外层双引号，产生 `|a b` 而非正确的 `"|a b"`。
+
+### 定位
+`ts-src/js-cirru.mts:439` — `format_cirru_edn` 对字符串类型直接拼接 `"\ndo " + to_cirru_edn(data)`，跳过了 `writer.ts` 中 `generateLeaf` 的 `JSON.stringify` 引号回退逻辑。
+
+### 修复
+改为走 `writeCirruCode([[to_cirru_edn(data)]])` → `generateLeaf` 路径，利用已有的字符合法性检查（`isCharAllowed`）决定是否加引号。同时保持 `\ndo ... \n` 外围格式与 Rust 版本一致。
+
+### 文件变更
+- `ts-src/js-cirru.mts` — 字符串分支改用 `writeCirruCode` 格式化
+- `calcit/test-edn.cirru` — 新增含空格字符串和无空格字符串的测试用例

package/editing-history/archived/2026-06-29-0117-upgrade-doc-snapshot-migration.md

@@ -0,0 +1,2 @@
+- docs/run/upgrade.md: added snapshot migration section — documents the transition from two-file setup (calcit.cirru snapshot + compact.cirru compact code) to single calcit.cirru with compact code only, no separate snapshot file needed
+- Recommended: delete old snapshot file, compact code saved directly in calcit.cirru for cr command to use directly

package/editing-history/archived/2026-06-29-calcit-cli.md

@@ -0,0 +1,80 @@
+# calcit.cli / cr exec 完整实现
+
+## 概要
+
+实现 `cr exec` + `calcit.cli/*` 内建函数（共 77 个），让 Agent 用 Cirru heredoc 调用常用 `cr query` / `edit` / `tree` / `analyze` / `docs` 能力，绕开 Shell 转义。RFC：`RFCs/06-29-cr-exec-cli-builtins-rfc.md`。
+
+## 架构
+
+- **运行时**：`src/bin/injection/mod.rs` 注册 handler；**单一 options map 参数**（arity 1）
+- **参数解析**：`calcit_cli_args.rs` — `resolve_cli_args`、类型 coercion、默认值填充、command echo
+- **参数规格**：`calcit_cli_specs.rs` — 每个函数的 `CliArgSpec` 列表（语义化键名）
+- **元数据**：`src/cirru/calcit-core.cirru` 的 `|calcit.cli` — schema 为 `(:args $ [] (:: :map :tag :dynamic))`
+- **同步**：`python3 scripts/gen_calcit_cli_core.py`（从 mod.rs + calcit_cli_specs.rs 生成）
+- **约束**：`calcit_cli*` 不得依赖 `cli_handlers`（保证 `cr-wasm` 可编译）
+
+### 调用约定（2026-06-29 重构）
+
+```cirru
+calcit.cli/peek-def $ {} (:file-path |calcit.cirru) (:target |app.main/main!)
+```
+
+- 唯一参数为 options map；键为 tag（`:file-path`、`:target`、`:lines` 等）
+- 省略的可选键由 Rust 侧默认值填充；非 quiet 模式下 stderr echo 展示完整调用（含默认值）
+- 位置参数已移除（breaking change）
+
+| 文件 | 职责 |
+|------|------|
+| `calcit_cli_args.rs` | map 解析、echo、docs_hint 生成 |
+| `calcit_cli_specs.rs` | 77 个函数的参数 spec 常量 |
+| `calcit_cli.rs` | 基础 query/write、snapshot 读写、`load_calcit_snapshot_with_deps` |
+| `calcit_cli_tree.rs` | AST 树变换（delete/insert/wrap/cp/mv…） |
+| `calcit_cli_extra.rs` | edit/config/cirru 工具、trigger-inc、semver bump |
+| `calcit_cli_program.rs` | 加载 snapshot+modules+core 并 preprocess（analyze/validate） |
+| `calcit_cli_analyze.rs` | call/effects/count + check-types/weak-types |
+| `calcit_cli_query.rs` | show-pkg/ns、list-defs-by-tag、validate-file、search-*、list-host-procs |
+| `calcit_cli_docs.rs` | docs-agents/read/sections |
+| `src/type_coverage.rs` | check-types / weak-types 共享逻辑（`cr analyze` 与 calcit.cli 共用） |
+
+## 分批功能（合并记录）
+
+### 第一批：树/定义/import 写操作（17）
+
+`tree-delete` `tree-insert` `tree-wrap` `tree-unwrap` `tree-raise` `tree-cp` `tree-mv` `rename-def` `rm-def` `mv-def` `split-def` `add-ns` `edit-doc` `edit-schema` `add-example` `rm-import` `show-error`
+
+要点：`tree-wrap` 用 `self` leaf；`position` 同 CLI（`|before` `|after` 等）。
+
+### 第二批：edit/config/cirru（20）
+
+`rm-ns` `set-imports` `format-file` `show-doc` `show-ns-doc` `list-tags` `set-tags` `rm-example` `clear-examples` `set-examples` `tree-replace-leaf` `tree-swap-*` `tree-batch-delete` `tree-rewrite` `set-config` `add/rm-module` `cirru-parse/format` `read-text-file`
+
+修复：`build_ns_code` 对齐 `(ns name (:require ...))` 嵌套结构。
+
+### 第三批：analyze / inc / docs 搜索（9）
+
+`trigger-inc` `cirru-parse-edn` `cirru-show-guide` `docs-search` `tree-replace-leaf-regex` `analyze-call-graph` `analyze-effects-graph` `analyze-count-calls`
+
+### 第四批：P0–P3（15）
+
+- **P0**：`show-pkg` `show-ns` `list-defs-by-tag` `validate-file` `bump-version` `edit-ns-doc`
+- **P1**：`search-project` `search-def-regex` `search-expr` `list-host-procs`
+- **P2**：`analyze-check-types` `analyze-weak-types`（依赖 `type_coverage` 提取）
+- **P3**：`docs-agents` `docs-read` `docs-sections`
+
+### Core 声明 + 预处理
+
+- core 可选参数 schema 用 `(:rest :dynamic)`，勿写 `:rest $ :dynamic`（EDN 解析失败）
+- 预处理：`is_registered_proc` 必须在 `has_def_code` 之前，避免 core 元数据 stub 被当作普通 def 编译（`preprocess/mod.rs`）
+
+## 验证
+
+```bash
+python3 scripts/gen_calcit_cli_core.py
+unset CARGO_TARGET_DIR && cargo fmt
+cargo clippy --all-targets -- -D warnings
+cargo test --bin cr
+./target/debug/cr calcit/test.cirru exec << 'EOF'
+calcit.cli/show-pkg $ {} (:file-path |calcit/test.cirru)
+calcit.cli/validate-file $ {} (:file-path |calcit/test.cirru)
+EOF
+```

package/editing-history/archived/2026-06-29-typed-calcit-cli-schemas.md

@@ -0,0 +1,23 @@
+# calcit.cli 选项 map 类型化 schema（Rust spec 直检）
+
+## 变更概要
+
+- 选项 spec 收敛到 `src/builtins/cli_options.rs`（Rust 单一来源），注册时写入 `RegisteredProcDescriptor.cli_options`。
+- preprocess 直接读 Rust spec 校验 options map，不再生成 defstruct / 不做 map→record 转换。
+- core 中 `:args` 仍由脚本生成 inline 类型 map（供 query/docs），校验走 Rust 而非 Calcit 类型系统。
+
+## 后续优化（Rust spec 直检）
+
+- preprocess 热路径改用 `registered_proc_cli_options()`，不再 clone 整个 `RegisteredProcDescriptor`。
+- `registered_proc_has_tag` 同样改为只读 map 查询。
+- `check_cli_options_map` 与 `resolve_cli_args` 共用 `collect_validation_errors`，preprocess 侧用引用收集 map 条目，避免多余 clone。
+- Registered 调用检查复用已有的 `processed_args`，去掉重复 `ys.drop_left()` 和 `alias` clone。
+
+## 验证案例（cr eval）
+
+| 案例 | 结果 |
+|------|------|
+| `:file-pth` 拼写错误 | `W_CLI_OPTION_UNKNOWN_KEY` |
+| 缺少 `:file-path` | `W_CLI_OPTION_MISSING_REQUIRED` |
+| `:lines \|bad` 类型错误 | `W_CLI_OPTION_TYPE_MISMATCH` |
+| 正确调用 | Check passed |