@calcit/procs 0.11.5 → 0.11.7

package/README.md

@@ -50,11 +50,11 @@ cr eval 'thread-first 100 range (map $ \ * % %)'
 Run with a [compact.cirru](https://github.com/calcit-lang/lilac/blob/main/compact.cirru):
 
 ```bash
-cr compact.cirru -1 # run only once
+cr compact.cirru # run once (default)
 
-cr -1 # by default, it picks `compact.cirru`
+cr # by default, it picks `compact.cirru`
 
-cr # watch mode enabled by default
+cr -w # watch mode (explicit flag required)
 ```
 
 By default Calcit reads `:init-fn` and `:reload-fn` inside `compact.cirru` configs. You may also specify functions,

package/editing-history/2026-0223-0834-migrate-to-defstruct.md

@@ -0,0 +1,91 @@
+# 2026-0223-0834 — 迁移到 defstruct 方案并实现 `%{}?` 可选字段 Record 宏
+
+## 背景
+
+将 Calcit Record 系统从旧的 `new-record`/`defrecord`/`defrecord!` 方案全面迁移到基于 `defstruct` 的新方案，同时新增 `%{}?` / `&%{}?` 支持可选字段初始化与更新。
+
+---
+
+## 知识点一：`%{}?` 与 `&%{}?` 的语义设计
+
+`struct` 初始化为 record 时，部分字段在语义上是可选的，对应 TypeScript 中的 `{ a?: number; b?: number }`。原有的 `%{}` / `&%{}` 要求所有字段都必须显式传入。
+
+### `%{}?`（macro）
+
+- 初始化 record 时允许省略字段，省略的字段自动填 `nil`。
+- 用法：`%{}? MyRecord (:x 1)`
+
+### `&%{}?`（proc）
+
+`call_record_partial` 的语义：
+
+- **proto 是 Struct**：以全 `nil` 为基础 `values`，用传入的 k-v 覆盖对应位置。
+- 传入未知字段 → 报错；传入重复字段 → 报错；`(args_size - 1) % 2 != 0` → 报错。
+
+关键实现细节：`CalcitStruct.fields` 元素类型是 `EdnTag`，比较时用 `f.ref_str()` 而非 `f.as_ref()`（后者无 `AsRef` impl）。
+
+### `%{}?` 宏定义
+
+```cirru
+defmacro %{}? (R & xs)
+  if
+    not $ and (list? xs) (every? xs list?)
+    raise $ str-spaced "|%{}? expects field entries in list, got:" xs
+  &let
+    args $ &list:concat & xs
+    quasiquote $ &%{}? ~R ~@args
+```
+
+---
+
+## 知识点二：Rust proc 注册流程
+
+新增一个内置 proc 需要同时修改四处：
+
+| 文件                       | 修改内容                                                 |
+| -------------------------- | -------------------------------------------------------- |
+| `src/calcit/proc_name.rs`  | 添加枚举变体 `NativeRecordPartial` + `ProcTypeSignature` |
+| `src/builtins/records.rs`  | 实现 `call_record_partial` 函数                          |
+| `src/builtins.rs`          | 在 `match proc` 中添加分发分支                           |
+| `src/runner/preprocess.rs` | 将新 proc 加入"跳过 arity 检查"的 `matches!` 列表        |
+
+---
+
+## 知识点三：`%{}` 严格要求 Struct proto
+
+- `call_record`（`%{}`）：若 proto 为 `Calcit::Record`，直接返回错误提示改用 `defstruct`。
+- `defstruct` 产生 `Calcit::Struct`（含 `field_types`），并作为 `%{}` / `%{}?` 的唯一原型来源。
+
+### `&record:get-name` / `&record:struct` 的参数约束
+
+- 两者统一要求传入 `record`，避免 `struct` / `record` 混用语义。
+
+### `&record:matches?` 的参数约束
+
+- 第一参数要求 `record`。
+- 第二参数接受 `record` 或 `struct`（用于 `record-match` 的模式匹配场景）。
+
+---
+
+## 修改文件
+
+| 文件                          | 变更内容                                                                                                      |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `src/calcit/proc_name.rs`     | 新增 `NativeRecordPartial` 枚举变体与类型签名；移除 `NewRecord` 变体                                          |
+| `src/builtins/records.rs`     | 新增 `call_record_partial`（struct-only）；`matches` 调整为 `(record, record/struct)`；移除 `new_record` 函数 |
+| `src/builtins.rs`             | 分发 `NativeRecordPartial`；移除 `NewRecord` 分发                                                             |
+| `src/runner/preprocess.rs`    | arity 检查豁免新增 `NativeRecordPartial`                                                                      |
+| `src/cirru/calcit-core.cirru` | 新增 `%{}?` 宏定义与 `&%{}?` 文档条目；`defrecord`/`defrecord!` 改为 raise error；删除 `new-record` 定义      |
+| `calcit/test-record.cirru`    | Cat/BirdShape/Person/City/A/B/C/Demo 全部改为 `defstruct`；删除所有 `new-record` let 绑定；修复各测试函数体   |
+| `docs/CalcitAgent.md`         | 类型标注示例中 `new-record` 改为 `defstruct`                                                                  |
+
+---
+
+## 验证
+
+```bash
+cargo run --bin cr -- calcit/test-record.cirru -1
+cargo clippy -- -D warnings
+```
+
+全部通过，无 warning。

package/editing-history/2026-0223-2321-ns-imports-code-fixes.md

@@ -0,0 +1,42 @@
+# 2026-0223 命名空间 imports 操作 Bug 修复
+
+## 背景
+
+通过在 `demos/compact.cirru` 上逐一测试 `cr edit` 的 namespace 相关子命令，发现三处导致 Agent 频繁用错的根本原因。
+
+## 发现的 Bug
+
+### Bug 1：`imports -e 'rule'` 产生平坦结构，与 `extract_require_rules` 不兼容
+
+- **现象**：`imports -e 'respo.core :refer $ sym'` 成功，但之后执行 `add-import` 会丢失已有 imports
+- **根因**：`handle_imports` 手工拼接 `ns_code_items`（平坦 list），产生结构：
+  ```
+  ["ns", "my.ns", ":require", "respo.core", ":refer", "$", "sym"]
+  ```
+  而 `extract_require_rules`/`build_ns_code` 期望嵌套结构：
+  ```
+  ["ns", "my.ns", [":require", ["respo.core", ":refer", "$", "sym"]]]
+  ```
+  导致后续任何依赖 `extract_require_rules` 的操作（`add-import`、`rm-import`）全部解析不到已有规则。
+- **修复**：重写 `handle_imports` 的 rules 解析逻辑，统一调用 `build_ns_code` 生成嵌套结构。同时自动区分输入是单条规则（flat array of strings）还是多条规则（array of arrays）。
+
+### Bug 2：`imports -e ':require ...'` 静默产生 `:require :require` 重复
+
+- **现象**：写 `:require respo.core :refer $ sym` 不报错，但生成 `ns my.ns :require :require respo.core ...`
+- **修复**：当 Cirru 解析后发现数组第一元素为 `:require` 字符串，立即返回错误消息，引导用户不包含 `:require` 前缀。
+
+### Bug 3：`add-ns -e 'ns WRONG_NAME ...'` 名称不一致静默通过
+
+- **现象**：`cr edit add-ns my.ns -e 'ns wrong.ns ...'` 成功，file-key 是 `my.ns`，但 ns 声明内写的是 `wrong.ns`，导致 `query ns my.ns` 看到内部名称错误
+- **修复**：当输入解析为 `ns` 表达式时，校验第二个元素是否与位置参数一致，不一致则 Error。
+
+## 修改文件
+
+- `src/bin/cli_handlers/edit.rs`：`handle_imports`、`handle_add_ns` 函数
+
+## 知识点
+
+- `imports` 命令的 `-e` 输入格式：**不含 `:require` 前缀**，直接是规则体（`src-ns :refer $ sym`）。单条规则传平坦字符串，多条规则用 `-f` 文件（每行一条）或 `-j` JSON 数组（元素为数组）。
+- `add-import` 和 `imports` 的格式一致，都是 `src-ns :refer $ sym`（无 `:require` 前缀）。
+- `add-ns -e` 中若传完整 `ns` 表达式，内部名称必须与位置参数完全匹配。
+- 最佳实践：优先使用 `add-import`（带保护和覆盖控制），`imports` 只在需要全量重置时使用。

package/editing-history/2026-0225-0002-language-behavior-eval-mode.md

@@ -0,0 +1,93 @@
+# 2026-0225-0002 eval 模式下的语言行为要点
+
+通过对 guidebook 文档代码块进行 eval 验证，发现以下 Calcit 运行时与预处理器的关键行为。
+
+## `list-match` 仅适用于 List，不接受 Tuple
+
+`list-match` 的展开宏内部调用 `&list:slice`，该函数在 `src/builtins/lists.rs` 中要求输入为 `:list` 类型。
+若传入 `::` 创建的 tuple，预处理阶段报 `Proc &list:slice arg 1 expects type :list, but got :tuple`。
+
+正确用法只针对 list，且分支模式是 **`(head tail)`**，`tail` 是剩余元素组成的 list（不是按位置展开多个变量）：
+
+```cirru
+list-match ([] :point 10 20)
+  () |Empty
+  (h tl) ([] h tl)
+; => ([] :point ([] 10 20))
+```
+
+## `.-field` 属性访问是 JS codegen 专用
+
+`.-x p` 这类属性访问在 `src/codegen/emit_js.rs` 中实现，Rust 解释器（`src/runner/`）没有对应路径。
+eval 模式下报：`method kind access (.-x) is only available in JS codegen, not supported in Rust runtime`.
+
+替代方式：对 struct record 字段用 `(:field-name record)` 或 `get record :field-name`。
+
+## 数值/字符串字面量在 fn 体内裸行的解析问题
+
+`fn`/`defn` 体内，一个字面量（数值 `3.14159` 或字符串 `|demo`）若单独占一行，Cirru 解析器会把该行当作以字面量为 head 的调用列表，从而报 `unknown head 3.14159` 或 `unknown head |demo`。
+
+修复方式：加 `, ` 前缀强制作为数据表达式（expression terminator 后接值）：
+
+```cirru
+defn get-pi () :number
+  , 3.14159
+```
+
+## `tag-match` 要求 defenum variant 的 payload 数量严格匹配
+
+`:ok` 无 payload 类型时，`%:: E :ok 42` 传 1 个值报：`enum variant ok expects 0 payload(s), but received: 1`。
+需在 `defenum` 定义中声明对应类型：`defenum Result (:ok :number) (:err :string)`。
+
+该检查在 `src/runner/` 中 `%::` 调用路径执行（运行时，非预处理）。
+
+## 变量名遮蔽 calcit.core 时触发 warning 并中止 eval
+
+预处理器对以下 core 名字的遮蔽一律报 warning，而 eval 模式将任何 warning 视为错误：
+
+- `first` → 遮蔽 `calcit.core/first`
+- `rest` → 遮蔽 `calcit.core/rest`
+- 宏参数名 `cond` → 遮蔽 `calcit.core/cond`（在 `defmacro when-not (cond & body)` 中出现）
+
+命名建议：用 `n`, `tl`, `h`, `item` 等无冲突名。
+
+## `let (x 1)` 单括号写法是无效语法
+
+Cirru `let` 绑定在 `src/runner/` 中要求双层 list `((name value) ...)` 形式。
+`let (x 1)` 单括号会得到 `expects pairs in list for let, got: ([] 'x 1)` 错误。
+
+有效形式：
+
+```cirru
+; 多行缩进
+let
+    x 1
+  x
+
+; 单行（需双括号）
+let ((x 1)) x
+```
+
+## deftrait/defimpl/defenum/defstruct 在 let 绑定中可正常执行
+
+所有类型定义表达式都是普通可求值的形式（返回定义值），可放入 let 绑定：
+
+```cirru
+let
+    MyFoo $ deftrait MyFoo
+      :foo $ :: :fn ('T) ('T) :string
+    MyFooImpl $ defimpl MyFooImpl MyFoo
+      :foo $ fn (p) (str-spaced |foo (:name p))
+    Person0 $ defstruct Person (:name :string)
+    Person $ impl-traits Person0 MyFooImpl
+    p $ %{} Person (:name |Alice)
+  .foo p
+```
+
+这使得在 eval/check-md snippet 中也能完整测试 trait dispatch，无需顶层 `ns/def` 定义。
+`def` 是顶层定义专用，eval 模式下不可用，需替换为 `let (Name $ ...)` 形式。
+
+## 多行类型注解 tuple 在运行时报错
+
+`:: :fn ([] :number) :string` 的多行缩进形式中，最后 `:string` 独占一行，被运行时当作 field access 调用，导致错误。
+紧凑单行形式 `(:: :fn ([] :number) :string)` 可运行。

package/editing-history/2026-0225-0111-guidebook-no-check-block-upgrades.md

@@ -0,0 +1,52 @@
+# Guidebook No-Check Block Upgrades (2026-02-25)
+
+## 概要
+
+对 Calcit guidebook (`/Users/chenyong/repo/calcit-lang/guidebook`) 中的代码块进行系统性升级，
+将 `cirru.no-check` 标记替换为可验证的 `cirru` 或 `cirru.no-run` 块。
+
+## 修改范围
+
+### 1. `docs/features/static-analysis.md`
+
+**双重求值 Bug 修复**：
+
+- 原始代码：`assert= a ([] "b" 2 "a" 2)` 使用了导致误报的冗余赋值写法。
+- 修复为直接 `assert= (get xs :xs) ys` 模式，规避了 `$ (expr)` 双重求值陷阱。
+- 将 4 个 `cirru.no-check` 块正确转换为可运行/可类型检查的 `cirru` 块。
+
+**核心知识点**：在 `let` 绑定中 `x $ (f a)` 会将 `(f a)` 的结果再作为操作符调用，
+必须改为 `x (f a)` 或省略 `$` 的形式。
+
+### 2. `docs/features/tuples.md`
+
+**伪代码替换**：
+
+- 将 5 个含 `&tuple:with-class` 调用的 `cirru.no-check` 块全部移除或替换。
+- `&tuple:with-class` 已从语言中删除，不再作为公共 API 存在。
+- 涉及内部机制的 3 个伪代码块改为 `text` 或 `code` 块并加注释。
+- 保留可运行的 `cirru` 示例块（使用 `defrecord` / `defenum` 实际语法）。
+
+### 3. `docs/features/common-patterns.md`
+
+- 将 3 个 `cirru.no-check` 块改为 `cirru.no-run`（语法正确但不运行的说明性代码）。
+- 涉及 `println` 副作用型示例以及占位符 `...` 形式的模板代码。
+
+### 4. 其他文档
+
+- `docs/features/sets.md`, `docs/data/persistent-data.md`, `docs/features/hashmap.md` 等多处：
+  - 将说明性 `cirru.no-check` 改为 `cirru.no-run`（语法正确、无副作用但不执行）。
+  - 将可验证的示例改为 `cirru`（加入 `assert=` 或 `assert` 验证）。
+
+## 测试结果
+
+全量测试通过：`yarn check-all` → 188/188 ✅
+
+## 相关知识点
+
+- **`cirru.no-check` vs `cirru.no-run` vs `cirru`**：
+  - `cirru`：完全运行并类型检查，推断语法语义。
+  - `cirru.no-run`：语法和类型检查，但不执行（适合副作用或模板代码）。
+  - `cirru.no-check`：完全跳过检查（仅在代码不可验证时使用，如调用不存在的 API）。
+- **`check-md` 子命令**：`cr docs check-md <file>` 用于单文件验证，加快 debug 循环。
+- **双重求值陷阱**：`let` 中 `x $ (f a)` 等价于 `x ((f a))`，结果被再次调用，触发 "cannot be used as operator" 错误。

package/editing-history/2026-0225-0113-runtime-type-validation-and-macro-quoting.md

@@ -0,0 +1,41 @@
+# Runtime Type Validation & Macro Quoting Fix
+
+## Summary
+
+Added runtime type validation for struct record and enum tuple creation. Fixed `defstruct`/`defenum` macros to support complex type annotations (e.g., `(:optional :string)`) by conditionally quoting list-type forms in macro expansion.
+
+## Changes
+
+### 1. Runtime Type Validation (`src/calcit/type_annotation.rs`)
+
+- Added `value_matches_type_annotation(value: &Calcit, expected: &CalcitTypeAnnotation) -> bool`
+  - Checks if a runtime value matches a type annotation
+  - Handles all annotation variants: Bool, Number, String, Tag, List, Map, Set, Ref, Buffer, Tuple, Record, Struct, Enum, Trait, Optional (allows nil), Dynamic (always true), TypeVar (always true), etc.
+- Added `brief_type_of_value(value: &Calcit) -> &'static str` for error messages
+
+### 2. Type Checking at Record/Enum Creation
+
+- `src/builtins/records.rs`: Validates field values against struct `field_types` in:
+  - `call_record_with_prototype` (`%{}`)
+  - `call_record_partial` (`&%{}?`)
+  - `record_with` (`&record:with`)
+  - `record_from_map` (`&record:from-map`)
+- `src/builtins/meta.rs`: Validates enum payload values in `new_enum_tuple_no_class` (`%::`)
+
+### 3. Macro Quoting Fix (`src/cirru/calcit-core.cirru`)
+
+**Problem**: `defstruct` and `defenum` are macros that expand to `&struct::new`/`&enum::new` (procs). Proc arguments are fully evaluated at runtime. Complex type annotations like `(:optional :string)` were evaluated as function calls (`(:optional :string)` → `(get :string :optional)` → error).
+
+**Fix**: Conditionally quote type annotations in the macro expansion:
+
+- List-type forms (e.g., `(:optional :string)`) are wrapped in `(quote ...)` to prevent evaluation
+- Tag/symbol forms (e.g., `:string`, `Status`) are left unquoted for normal evaluation/resolution
+
+### 4. Test Updates (`calcit/test-record.cirru`)
+
+- `Lagopus0`: `:name :string` → `:name (:optional :string)`
+- `Person`: field types changed to `(:optional :type)` to support nil initialization
+
+## Key Insight
+
+`defstruct`/`defenum` are macros → expand to proc calls (`&struct::new`/`&enum::new`) → args are evaluated before the handler receives them. Nested list type annotations must be quoted to survive evaluation, but symbol type references (e.g., enum/struct names) must NOT be quoted so they resolve correctly. The fix uses `(list? type-form)` to discriminate.

package/editing-history/2026-0225-1131-check-md-eval-improvements.md

@@ -0,0 +1,13 @@
+# check-md and eval improvements
+
+- Added `docs check-md --dep` (repeatable) and forwarded deps to internal eval/check-only.
+- Added ns-first snippet handling in eval: merge `ns ...` tail nodes into `ns app.main`.
+- Added check-md hint when `cirru` blocks are fewer than `cirru.no-check` blocks.
+
+## 2026-02-26 follow-up
+
+- Refactored `docs check-md` to run `cirru` / `cirru.no-run` / `cirru.no-check` in-process instead of spawning `cr` subprocesses for each block.
+- Added shared dependency/core loading cache in `check-md` so modules and core snapshot load once per markdown file, then reuse per block.
+- Kept warning/error details visible in failed block output while preserving pass/fail summary behavior.
+- Simplified path display in logs and header output for default modules: replaced absolute module root with `<mods>/...` placeholder.
+- Shortened displayed `entry` path in `check-md` header by preferring current-directory relative paths when available.

package/editing-history/2026-0225-1234-watch-mode-default-once.md

@@ -0,0 +1,6 @@
+# watch mode default-once update
+
+- Unified run mode behavior for `cr`, `cr js`, and `cr ir`: default to once.
+- Added explicit `-w/--watch` switches for top-level direct run and `ir` subcommand.
+- Kept `-1/--once` for backward compatibility.
+- Updated watch-mode related docs in `Agents.md` and `docs/CalcitAgent.md`.

package/editing-history/2026-0226-1324-check-md-inprocess-cache-and-path-labels.md

@@ -0,0 +1,7 @@
+# check-md in-process cache and path labels
+
+- Replaced process-per-block `docs check-md` execution with in-process Rust checks for `cirru`, `cirru.no-run`, and `cirru.no-check`.
+- Added shared cache for deps/core loading in `check-md`, reducing repeated module/core startup per markdown block.
+- Kept warning/error details visible in block-level failure output.
+- Replaced default module absolute path displays with `<mods>/...` in `loading:` logs and `check-md` deps preview.
+- Normalized `check-md` entry path display to prefer current-directory relative path.

package/editing-history/2026-0227-1640-unify-markdown-readers.md

@@ -0,0 +1,16 @@
+# 2026-02-27 16:40
+
+## 知识点
+
+- 将 `docs read` / `docs agents` / `libs readme` 的 Markdown 读取行为统一到共享模块。
+- 共享能力包括：标题提取、章节匹配、`--full`、`--with-lines`、`--no-subheadings`、提示输出与无匹配错误处理。
+- `docs agents` 增加本地缓存刷新路径与长度展示，并复用统一渲染逻辑。
+- `libs readme` 对齐结构化读取参数，支持本地与远程 README 的一致体验。
+
+## 改动概要
+
+- 新增 `src/bin/cli_handlers/markdown_read.rs`，沉淀可复用的 markdown section 渲染流程。
+- `src/bin/cli_handlers/docs.rs` 切换为共享渲染入口，并精简参数传递结构。
+- `src/bin/cli_handlers/libs.rs` 切换为共享渲染入口，收敛本地/远程 header 打印样板。
+- `src/bin/cli_handlers/mod.rs` 注册新模块。
+- `src/cli_args.rs` 对齐 `libs readme` 参数与 `docs` 系列的一致性。

package/editing-history/2026-0227-1958-tree-rewrite-command-and-reference-model.md

@@ -0,0 +1,18 @@
+# 2026-02-27 19:58
+
+## 知识点
+
+- `tree structural` 改名为动词化的 `tree rewrite`，更贴近“结构重写”语义，也更容易让 AI 模型理解用途。
+- `rewrite` 明确为**引用驱动**命令：必须提供至少一个 `--with name=path`，否则应提示改用 `tree replace`。
+- 结构引用从旧的 `--refer-*` 模型统一为 `--with` 映射模型（如 `--with self=.`, `--with rhs=2`），减少参数心智负担。
+
+## 改动概要
+
+- CLI 路由与文案：`TreeSubcommand::Structural` 改为 `TreeSubcommand::Rewrite`，子命令名改为 `rewrite`。
+- `tree` handler：将 `handle_structural` 更名为 `handle_rewrite`，并更新输出提示与错误信息。
+- 结构引用处理：在 `tree` 中统一使用 `parse_with_references` + `process_node_with_references`。
+- 文档更新：`docs/CalcitAgent.md` 与 `Agents.md` 全部改用 `tree rewrite` 与 `--with` 示例。
+- 真实命令验证（基于 `demos/compact.cirru`）：
+  - `tree replace` 可执行普通替换；
+  - `tree rewrite` 无 `--with` 会按预期报错；
+  - `tree rewrite` 携带 `--with` 可按预期执行。

package/editing-history/2026-0227-2200-split-def-command.md

@@ -0,0 +1,29 @@
+# 202602272200 — 新增 `edit split-def` 命令
+
+## 改动概要
+
+新增 `cr edit split-def <ns/def> -p <path> -n <new-name>` 命令，用于将某定义内指定路径的子表达式提取为同命名空间内的一个新定义，原位置替换为新定义的名字。
+
+## 修改文件
+
+- `src/cli_args.rs`：新增 `EditSplitDefCommand` struct（参数：`target`, `-p/--path`, `-n/--name`）；在 `EditSubcommand` 枚举中新增 `SplitDef(EditSplitDefCommand)` 变体。
+- `src/bin/cli_handlers/edit.rs`：import 增加 `EditSplitDefCommand`；dispatch 增加 `EditSubcommand::SplitDef`；实现 `handle_split_def` 函数。
+- `docs/CalcitAgent.md`：
+  1. 修复 `tree unwrap` 示例（移除已废弃的 `-i 1` 参数，更新描述为 splice 所有子节点语义）。
+  2. 在"结构化变更示例"中增加 `split-def` 的使用示例。
+  3. 在"定义操作"列表中增加 `cr edit split-def` 条目。
+  4. 新增"🔧 实战重构场景"章节，列举提取子表达式、rename、mv-def、mv/cp、unwrap/rewrite、批量批量重命名等常见重构操作的完整命令序列。
+
+## 实现逻辑（`handle_split_def`）
+
+1. 用 `navigate_to_path` 读取指定路径的子节点（`extracted`）。
+2. 验证新名称在当前 ns 中不存在（不允许覆盖）。
+3. 用 `apply_operation_at_path(..., "replace", Some(&leaf_new_name))` 将原定义的该路径替换为引用叶子节点。
+4. 用 `CodeEntry::from_code(extracted)` 创建新定义，插入到同 ns 的 `defs` 中。
+5. 保存 snapshot。
+
+## 知识点
+
+- `split-def` 只操作 AST，不会自动添加 import。如果新定义需要被其他 ns 引用，需手动 `cr edit add-import`。
+- 路径索引规则与 `cr tree` 系列一致（逗号分隔，0-based）。
+- 提取后如需给新定义包装成 `defn` 函数形式，用 `cr tree replace <ns/new-name> -p '' -e 'defn new-name (args...) ...'`。

package/editing-history/2026-0227-2212-tree-raise-wrap.md

@@ -0,0 +1,33 @@
+# 202602272212 — 新增 `tree raise` 和 `tree wrap` 命令
+
+## 改动概要
+
+补齐两个 Lisp 社区（Paredit）常用的结构化编辑操作，完善 `cr tree` 命令集。
+
+## 修改文件
+
+- `src/cli_args.rs`：新增 `TreeRaiseCommand`、`TreeWrapCommand` 结构体；在 `TreeSubcommand` 枚举中新增 `Raise`、`Wrap` 变体。
+- `src/bin/cli_handlers/tree.rs`：import 增加两个命令结构体；dispatch 增加两个分支；新增 `handle_raise` 和 `handle_wrap` 函数。
+- `docs/CalcitAgent.md`：更新主要操作列表、结构化变更示例、实战重构场景。
+
+## 命令语义
+
+### `cr tree raise <ns/def> -p <child-path>`
+
+等价 Paredit `raise-sexp`。将指定子节点**整体替换掉其父节点**。
+
+- `path` 必须至少一个元素（才有父节点）
+- `parent_path = path[..n-1]`，用 `apply_operation_at_path(..., "replace", child)` 实现
+- 典型用途：去掉 `if` 只保留某分支、去掉 `let` 只保留最终返回值表达式
+
+### `cr tree wrap <ns/def> -p <path> -e '<template>'`
+
+等价 `cr tree rewrite ... -w 'self=.'`，但更简洁。模板中 `self` 自动绑定为原节点。
+
+- 适合"加一层调用"的常见模式：`wrap -e 'println self'`、`wrap -e 'let ((x self)) x'`
+- 当需要引用原节点的**子节点**（不只是整体）时，仍需用 `rewrite --with`
+
+## 知识点
+
+- 三个互相对应的操作：`wrap`（包裹）→ `unwrap`（所有子节点展开）→ `raise`（单子节点替换父）
+- `wrap` 与 `rewrite` 的关系：`wrap` = `rewrite` 固定了 `self=.` 的语法糖，降低常用操作的命令复杂度

package/editing-history/2026-0227-2223-calcit-agent-docs-optimize.md

@@ -0,0 +1,41 @@
+# 202602272223 CalcitAgent.md 优化：精简冷僻内容，补充实战示例
+
+## 修改概要
+
+对 `docs/CalcitAgent.md` 进行了三项优化，使文档对 Agent 更加实用：
+
+### 1. 精简 "LLM 辅助：动态方法提示" 一节
+
+**知识点**：低频场景的文档应指向 `cr docs`，而不是在主文档中展开细节。
+
+- 将 4 个内置函数的冗长说明（每个都有 3-4 行 `用法/用途/说明`）压缩为 4 行简要说明
+- 末尾加 `cr docs read traits.md` 和 `cr docs search 'trait-call'` 的指引入口
+- 减少约 300 字，信噪比更高
+
+### 2. 扩充 "常见错误排查" 一节
+
+**知识点**：错误排查文档需要配有"如何读懂错误"的示例，而不只是一张表格。
+
+变更：
+- 新增 **快速诊断流程** 子节：明确排查步骤（`cr query error` → `--check-only` → `cr eval` 隔离验证），并附带 `cr query error` 输出示例（含 unknown symbol 拼写错）
+- 扩展错误信息对照表：从 4 条扩展到 11 条，覆盖 `unknown symbol`、`let` 语法、`cannot be used as operator`、`foldl` 参数顺序、`imports` `:require` 前缀格式等高频错误，每条均有解决命令
+- 新增 **调试常用命令** 子节：汇总 `cr query error`、`cr eval`、`cr query find`、`cr cirru parse` 等常用排查命令
+- 新增 `.calcit-error.cirru` 备份文件的说明（比 `cr query error` 更完整）
+
+### 3. 新增 "🔄 完整功能开发示例" 一节
+
+**知识点**：Agent 最常见的任务是"添加新函数"，需要端到端的完整流程示例。
+
+内容：
+- 步骤 1: `cr query ns` / `cr query defs` / `cr query peek` 确认现有代码
+- 步骤 2: `cr eval` 快速验证写法（含 `--dep` 加载模块的示例）
+- 步骤 3: `cr edit def` 添加新定义
+- 步骤 4: `cr edit add-import` 添加 import，`cr tree replace` 在调用方使用新定义
+- 步骤 5: `cr edit inc --changed` 触发热更新 + `cr query error` 验证 + `cr --check-only` 整体检查
+- 末尾附"常见失误快速修复"（忘记 import、拼写错误、参数顺序错误）
+
+## 关联规则
+
+- 冷僻/参考类内容应精简，提供 `cr docs search / read` 入口
+- 高频场景应提供完整示例（搜索→修改→验证→热更新）
+- 错误排查文档必须包含错误内容预览，而不只是表格

package/editing-history/2026-0301-0212-query-search-entry-and-ffi-warning.md

@@ -0,0 +1,53 @@
+# 2026-0301-0212 query search entry + ffi warning 简化
+
+## 修改概要
+
+本次包含两类改动：
+
+1. `cr query search` / `cr query search-expr` 支持 `--entry <name>`
+2. 简化 FFI 回调接口实验性告警（去除低价值 warn）
+
+## 知识点
+
+### 1) search 默认依赖加载来源
+
+`query` 之前只从 `configs.modules` 加载模块。
+对于把依赖配置在 `entries.<name>.modules` 的项目，`search`/`search-expr` 可能漏搜。
+
+### 2) entry 级依赖叠加策略
+
+新增 `load_snapshot_with_entry(input_path, entry)`：
+
+- 默认加载 `configs.modules`
+- 指定 `--entry` 时，再叠加 `entries.<entry>.modules`
+- 对模块路径去重（保持顺序）
+- entry 不存在时给出可用 entries 列表
+
+### 3) FFI 回调接口稳定性
+
+`&call-dylib-edn-fn` 与 `&blocking-dylib-edn-fn` 原先标记为 `Experimental`，触发
+`registered proc ... is marked as experimental` 告警。
+
+当前 FFI 功能已稳定、该警告噪声较大，因此将这两个接口标记为 `Public`，保留参数校验与平台校验逻辑不变。
+
+## 变更文件
+
+- `src/cli_args.rs`
+  - 为 `QuerySearchCommand`、`QuerySearchExprCommand` 增加 `--entry` 选项
+
+- `src/bin/cli_handlers/query.rs`
+  - search / search-expr 参数透传 `entry`
+  - 新增 `load_snapshot_with_entry`
+  - search 输出中显示 `Entry: <name>`
+
+- `src/bin/injection/mod.rs`
+  - `&call-dylib-edn-fn` descriptor: `Experimental -> Public`
+  - `&blocking-dylib-edn-fn` descriptor: `Experimental -> Public`
+  - 注释中移除 experimental 字样
+
+- `docs/CalcitAgent.md`
+  - 为 `query search` / `search-expr` 增加 `--entry` 说明
+
+## 验证
+
+- `cargo build --release --bin cr` 通过

package/lib/js-record.mjs

@@ -169,6 +169,34 @@ export let _$n__PCT__$M_ = (proto, ...xs) => {
         return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
     }
 };
+export let _$n__PCT__$M__$q_ = (proto, ...xs) => {
+    let recordProto;
+    let values;
+    if (proto instanceof CalcitStruct) {
+        recordProto = new CalcitRecord(proto.name, proto.fields, new Array(proto.fields.length).fill(null), proto);
+        values = recordProto.values.slice();
+    }
+    else {
+        throw new Error("Expected prototype to be a struct");
+    }
+    if (xs.length % 2 !== 0) {
+        throw new Error("Expected even number of key/value");
+    }
+    let touched = new Set();
+    for (let i = 0; i < xs.length; i += 2) {
+        let k = castTag(xs[i]);
+        let idx = findInFields(recordProto.fields, k);
+        if (idx < 0) {
+            throw new Error(`Cannot find field ${k} among ${recordProto.fields}`);
+        }
+        if (touched.has(idx)) {
+            throw new Error(`record field already has value, probably duplicated key: ${k}`);
+        }
+        touched.add(idx);
+        values[idx] = xs[i + 1];
+    }
+    return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
+};
 /// update record with new values
 export let _$n_record_$o_with = (proto, ...xs) => {
     if (proto instanceof CalcitRecord) {
@@ -208,23 +236,28 @@ export let _$n_record_$o_struct = (x) => {
     }
 };
 export let _$n_record_$o_from_map = (proto, data) => {
-    if (!(proto instanceof CalcitRecord))
-        throw new Error("Expected prototype to be record");
+    let recordProto;
+    if (proto instanceof CalcitStruct) {
+        recordProto = new CalcitRecord(proto.name, proto.fields, new Array(proto.fields.length).fill(null), proto);
+    }
+    else {
+        throw new Error("Expected prototype to be struct");
+    }
     if (data instanceof CalcitRecord) {
-        if (fieldsEqual(proto.fields, data.fields)) {
-            return new CalcitRecord(proto.name, proto.fields, data.values);
+        if (fieldsEqual(recordProto.fields, data.fields)) {
+            return new CalcitRecord(recordProto.name, recordProto.fields, data.values, recordProto.structRef);
         }
         else {
             let values = [];
-            for (let i = 0; i < proto.fields.length; i++) {
-                let field = proto.fields[i];
+            for (let i = 0; i < recordProto.fields.length; i++) {
+                let field = recordProto.fields[i];
                 let idx = findInFields(data.fields, field);
                 if (idx < 0) {
                     throw new Error(`Cannot find field ${field} among ${data.fields}`);
                 }
                 values.push(data.values[idx]);
             }
-            return new CalcitRecord(proto.name, proto.fields, values);
+            return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
         }
     }
     else if (data instanceof CalcitMap || data instanceof CalcitSliceMap) {
@@ -238,8 +271,8 @@ export let _$n_record_$o_from_map = (proto, data) => {
         // mutable sort
         pairs_buffer.sort((pair1, pair2) => pair1[0].cmp(pair2[0]));
         let values = [];
-        outerLoop: for (let i = 0; i < proto.fields.length; i++) {
-            let field = proto.fields[i];
+        outerLoop: for (let i = 0; i < recordProto.fields.length; i++) {
+            let field = recordProto.fields[i];
             for (let idx = 0; idx < pairs_buffer.length; idx++) {
                 let pair = pairs_buffer[idx];
                 if (pair[0] === field) {
@@ -249,7 +282,7 @@ export let _$n_record_$o_from_map = (proto, data) => {
             }
             throw new Error(`Cannot find field ${field} among ${pairs_buffer}`);
         }
-        return new CalcitRecord(proto.name, proto.fields, values);
+        return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
     }
     else {
         throw new Error("Expected record or data for making a record");
@@ -268,16 +301,25 @@ export let _$n_record_$o_to_map = (x) => {
     }
 };
 export let _$n_record_$o_matches_$q_ = (x, y) => {
-    if (!(x instanceof CalcitRecord)) {
-        throw new Error("Expected first argument to be record");
+    let targetStruct;
+    if (y instanceof CalcitRecord) {
+        targetStruct = y.structRef;
     }
-    if (!(y instanceof CalcitRecord)) {
-        throw new Error("Expected second argument to be record");
+    else if (y instanceof CalcitStruct) {
+        targetStruct = y;
     }
-    if (x.name !== y.name) {
-        return false;
+    else {
+        throw new Error("Expected second argument to be record or struct");
+    }
+    if (x instanceof CalcitRecord) {
+        if (x.name !== targetStruct.name) {
+            return false;
+        }
+        return fieldsEqual(x.fields, targetStruct.fields);
+    }
+    else {
+        throw new Error("Expected first argument to be record");
     }
-    return fieldsEqual(x.fields, y.fields);
 };
 export function _$n_record_$o_extend_as(obj, new_name, new_key, new_value) {
     if (arguments.length !== 4)

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.11.5",
+    "version": "0.11.7",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.11.5",
+  "version": "0.11.7",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",

package/ts-src/js-record.mts

@@ -176,6 +176,37 @@ export let _$n__PCT__$M_ = (proto: CalcitValue, ...xs: Array<CalcitValue>): Calc
   }
 };
 
+export let _$n__PCT__$M__$q_ = (proto: CalcitValue, ...xs: Array<CalcitValue>): CalcitValue => {
+  let recordProto: CalcitRecord;
+  let values: Array<CalcitValue>;
+  if (proto instanceof CalcitStruct) {
+    recordProto = new CalcitRecord(proto.name, proto.fields, new Array(proto.fields.length).fill(null), proto);
+    values = recordProto.values.slice();
+  } else {
+    throw new Error("Expected prototype to be a struct");
+  }
+
+  if (xs.length % 2 !== 0) {
+    throw new Error("Expected even number of key/value");
+  }
+
+  let touched = new Set<number>();
+  for (let i = 0; i < xs.length; i += 2) {
+    let k = castTag(xs[i]);
+    let idx = findInFields(recordProto.fields, k);
+    if (idx < 0) {
+      throw new Error(`Cannot find field ${k} among ${recordProto.fields}`);
+    }
+    if (touched.has(idx)) {
+      throw new Error(`record field already has value, probably duplicated key: ${k}`);
+    }
+    touched.add(idx);
+    values[idx] = xs[i + 1];
+  }
+
+  return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
+};
+
 /// update record with new values
 export let _$n_record_$o_with = (proto: CalcitValue, ...xs: Array<CalcitValue>): CalcitValue => {
   if (proto instanceof CalcitRecord) {
@@ -198,7 +229,7 @@ export let _$n_record_$o_with = (proto: CalcitValue, ...xs: Array<CalcitValue>):
   }
 };
 
-export let _$n_record_$o_get_name = (x: CalcitRecord): CalcitTag => {
+export let _$n_record_$o_get_name = (x: CalcitValue): CalcitTag => {
   if (x instanceof CalcitRecord) {
     return x.name;
   } else {
@@ -206,7 +237,7 @@ export let _$n_record_$o_get_name = (x: CalcitRecord): CalcitTag => {
   }
 };
 
-export let _$n_record_$o_struct = (x: CalcitRecord): CalcitValue => {
+export let _$n_record_$o_struct = (x: CalcitValue): CalcitValue => {
   if (x instanceof CalcitRecord) {
     return x.structRef ?? null;
   } else {
@@ -215,22 +246,27 @@ export let _$n_record_$o_struct = (x: CalcitRecord): CalcitValue => {
 };
 
 export let _$n_record_$o_from_map = (proto: CalcitValue, data: CalcitValue): CalcitValue => {
-  if (!(proto instanceof CalcitRecord)) throw new Error("Expected prototype to be record");
+  let recordProto: CalcitRecord;
+  if (proto instanceof CalcitStruct) {
+    recordProto = new CalcitRecord(proto.name, proto.fields, new Array(proto.fields.length).fill(null), proto);
+  } else {
+    throw new Error("Expected prototype to be struct");
+  }
 
   if (data instanceof CalcitRecord) {
-    if (fieldsEqual(proto.fields, data.fields)) {
-      return new CalcitRecord(proto.name, proto.fields, data.values);
+    if (fieldsEqual(recordProto.fields, data.fields)) {
+      return new CalcitRecord(recordProto.name, recordProto.fields, data.values, recordProto.structRef);
     } else {
       let values: Array<CalcitValue> = [];
-      for (let i = 0; i < proto.fields.length; i++) {
-        let field = proto.fields[i];
+      for (let i = 0; i < recordProto.fields.length; i++) {
+        let field = recordProto.fields[i];
         let idx = findInFields(data.fields, field);
         if (idx < 0) {
           throw new Error(`Cannot find field ${field} among ${data.fields}`);
         }
         values.push(data.values[idx]);
       }
-      return new CalcitRecord(proto.name, proto.fields, values);
+      return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
     }
   } else if (data instanceof CalcitMap || data instanceof CalcitSliceMap) {
     let pairs_buffer: Array<[CalcitTag, CalcitValue]> = [];
@@ -244,8 +280,8 @@ export let _$n_record_$o_from_map = (proto: CalcitValue, data: CalcitValue): Cal
     pairs_buffer.sort((pair1, pair2) => pair1[0].cmp(pair2[0]));
 
     let values: Array<CalcitValue> = [];
-    outerLoop: for (let i = 0; i < proto.fields.length; i++) {
-      let field = proto.fields[i];
+    outerLoop: for (let i = 0; i < recordProto.fields.length; i++) {
+      let field = recordProto.fields[i];
       for (let idx = 0; idx < pairs_buffer.length; idx++) {
         let pair = pairs_buffer[idx];
         if (pair[0] === field) {
@@ -255,7 +291,7 @@ export let _$n_record_$o_from_map = (proto: CalcitValue, data: CalcitValue): Cal
       }
       throw new Error(`Cannot find field ${field} among ${pairs_buffer}`);
     }
-    return new CalcitRecord(proto.name, proto.fields, values);
+    return new CalcitRecord(recordProto.name, recordProto.fields, values, recordProto.structRef);
   } else {
     throw new Error("Expected record or data for making a record");
   }
@@ -274,17 +310,23 @@ export let _$n_record_$o_to_map = (x: CalcitValue): CalcitValue => {
 };
 
 export let _$n_record_$o_matches_$q_ = (x: CalcitValue, y: CalcitValue): boolean => {
-  if (!(x instanceof CalcitRecord)) {
-    throw new Error("Expected first argument to be record");
-  }
-  if (!(y instanceof CalcitRecord)) {
-    throw new Error("Expected second argument to be record");
+  let targetStruct: CalcitStruct;
+  if (y instanceof CalcitRecord) {
+    targetStruct = y.structRef;
+  } else if (y instanceof CalcitStruct) {
+    targetStruct = y;
+  } else {
+    throw new Error("Expected second argument to be record or struct");
   }
 
-  if (x.name !== y.name) {
-    return false;
+  if (x instanceof CalcitRecord) {
+    if (x.name !== targetStruct.name) {
+      return false;
+    }
+    return fieldsEqual(x.fields, targetStruct.fields);
+  } else {
+    throw new Error("Expected first argument to be record");
   }
-  return fieldsEqual(x.fields, y.fields);
 };
 
 export function _$n_record_$o_extend_as(obj: CalcitValue, new_name: CalcitValue, new_key: CalcitValue, new_value: CalcitValue) {