@calcit/procs 0.12.55 → 0.12.57

package/editing-history/2026-02-14-2358-emit-js-modularization-shift-left.md

@@ -1,63 +0,0 @@
-# 2026-02-14 23:58 emit_js modularization + shift-left contracts
-
-## Scope
-
-This round focuses on two tracks:
-
-1. Continue low-risk modularization of `src/codegen/emit_js.rs` without changing runtime semantics.
-2. Introduce AI-oriented "shift-left" validation contracts for expected warning/error paths.
-
-## What changed
-
-### Rust codegen modularization
-
-- Removed duplicate legacy module file:
-  - `src/calcit/struct.rs`
-- Split helpers from `emit_js.rs` into cohesive submodules:
-  - `src/codegen/emit_js/tags.rs`
-  - `src/codegen/emit_js/symbols.rs`
-  - `src/codegen/emit_js/paths.rs`
-  - `src/codegen/emit_js/runtime.rs`
-  - `src/codegen/emit_js/args.rs`
-  - `src/codegen/emit_js/deps.rs`
-  - `src/codegen/emit_js/helpers.rs`
-- Kept behavior stable by only moving logic and wiring imports/call sites.
-- Added targeted unit tests in extracted modules.
-
-### Runtime helper boundary cleanup (TS)
-
-- Grouped runtime helpers into dedicated modules:
-  - `ts-src/js-arity-helpers.mts` (`_args_throw`, `_args_fewer_throw`, `_args_between_throw`)
-  - `ts-src/js-tag-helpers.mts` (`init_tags` + internal cache)
-- Switched `ts-src/calcit.procs.mts` to re-export these modules, keeping public API names unchanged.
-
-### Test/validation workflow improvements
-
-- Added contract-based shift-left script:
-  - `scripts/check-shift-left.mjs`
-- Added npm script:
-  - `check-shift-left` in `package.json`
-- This script enforces both:
-  - positive baseline must pass (`calcit/test.cirru -1`)
-  - selected negative cases must fail with expected diagnostic tokens.
-
-### Planning/documentation updates
-
-- Expanded and updated roadmap status:
-  - `drafts/project-modernization-roadmap.md`
-- Added AI-oriented long-term section for:
-  - immutable core constraints
-  - earlier error detection
-  - contractized diagnostics
-  - staged execution strategy.
-
-## Verification
-
-- Ran targeted unit tests for extracted modules (`tags/symbols/paths/runtime/args/deps/helpers` where applicable).
-- Repeated full validation with `yarn check-all` after each refactor batch.
-- Ran `yarn check-shift-left` to validate diagnostic contracts.
-
-## Notes
-
-- Some standalone `calcit/test-*.cirru` files are intentionally warning/error reproductions or independent package entries; they are not safe to inline into `test.cirru` module list directly.
-- Using a separate shift-left contract script avoids namespace collisions and preserves intent.

package/editing-history/2026-02-15-0000-diagnostics-consolidated.md

@@ -1,35 +0,0 @@
-# 2026-02-15 diagnostics 合并记录
-
-本文件合并以下 diagnostics 相关记录，避免碎片化：
-
-- 2026-0215-1011-preprocess-diagnostic-v1.md
-- 2026-0215-1026-cli-diag-json.md
-- 2026-0215-1104-diag-expected-actual-action-let.md
-- 2026-0215-1110-eval-diag-fallbacks.md
-- 2026-0215-1116-macro-diagnostic-protocol.md
-- 2026-0215-1134-macro-diag-expansion-if-defn-assert.md
-- 2026-0215-1152-runtime-fallback-tag-match-arity.md
-- 2026-0215-1202-warning-arity-fallback-compat.md
-- 2026-0215-1211-warning-learning-fields.md
-- 2026-0215-1238-convergence-help-docs-diag.md
-- 2026-0215-1306-text-diagnostics-convergence-fix.md
-- 2026-0215-1332-diagnostics-simplification-example-driven.md
-
-## 合并后的结论（当前保留）
-
-- 已移除 `--diag json` 路径，CLI 统一使用文本诊断输出。
-- warning 维持最小字段与文本展示，不再维护 JSON 结构演进。
-- error 维持 call stack + examples 辅助定位，避免复杂规则映射。
-- 文本模式保持简洁：优先 message/hint/location/stack，便于直接修复。
-
-## 本轮简化（减法）
-
-- 移除 warning 侧复杂增强字段：`fingerprint/convergence/help/learning`。
-- 移除 error 侧复杂增强字段：`fingerprint/convergence/help/learning` 与大段规则映射。
-- 将 error 的 expected/actual/action 处理改为“hint 优先 + 通用 message 提取 + 最小 fallback”。
-
-## 设计原则（后续继续遵循）
-
-- 诊断能力优先复用编译器已有信息（hint、message、stack、examples）。
-- 尽量减少按错误码硬编码规则，避免语言层复杂度膨胀。
-- LLM 修复入口尽量通用化：`query examples` + 最小可执行动作。

package/editing-history/2026-02-15-1941-macro-diagnostics-refinement.md

@@ -1,39 +0,0 @@
-# Macro Diagnostics Refinement (2026-02-15 19:41)
-
-## Summary
-
-This change improves diagnostic quality for macro misuse and warning flows without changing macro semantics.
-
-## Key updates
-
-- Added a shared diagnostics helper module:
-  - `src/diagnostics_help.rs`
-  - Centralizes message-to-help inference logic.
-- Improved stack-rendered failure guidance:
-  - `src/call_stack.rs`
-  - Uses macro-context-aware help text.
-  - Keeps examples targeting user-facing macros over internal helper macros.
-- Improved warning-path guidance:
-  - `src/bin/cr.rs`
-  - Reuses shared help inference for preprocessing/codegen warning blocks.
-- Improved macro argument binding diagnostics in runtime:
-  - `src/runner.rs`
-  - Replaces low-level `Idx(...)` style arity failures with readable signatures and missing argument names.
-- Refined macro-side error wording:
-  - `src/cirru/calcit-core.cirru`
-  - Better `list-match` branch-shape messages.
-- Kept macro signatures intact where requested:
-  - `when`, `when-not`, `when-let` remain with explicit parameter forms.
-
-## Validation
-
-- Spot checks executed with `cr eval` for macro misuse cases:
-  - `when`, `when-not`, `when-let`, `if-not`, `tag-match`, `record-match`, `list-match`, `cond`, `let`, `thread-first`, `thread-last`.
-- Confirmed help text differentiates macro misuse vs proc/function arity warnings.
-- Full regression passed:
-  - `yarn check-all` => `EXIT:0`.
-
-## Notes
-
-- This iteration focuses on user-facing diagnostics quality.
-- Behavior and compatibility are preserved; changes are primarily in error/help reporting paths.

package/editing-history/2026-02-16-2043-core-api-docs-cleanup.md

@@ -1,40 +0,0 @@
-# 2026-02-16 20:43 core API/docs cleanup
-
-## Scope
-
-- Cleaned outdated draft references and status notes.
-- Aligned core internal API names around trait attachment (`*:impl-traits`).
-- Fixed `wo-js-log` export/definition mismatch.
-- Merged symbol-resolution note into drafts and removed duplicated doc file.
-
-## Key updates
-
-1. **drafts cleanup**
-   - Added `drafts/README.md` as a state index (active/review-needed/archived).
-   - Fixed stale links between `assert-types-plan.md` and `assert-types.md`.
-   - Marked `drafts/last-session.md` as archived historical snapshot.
-
-2. **core naming consistency**
-   - Updated internal entries in `src/cirru/calcit-core.cirru`:
-     - `&record:with-impls` -> `&record:impl-traits`
-     - `&tuple:with-impls` -> `&tuple:impl-traits`
-     - `&struct:with-impls` -> `&struct:impl-traits`
-     - `&enum:with-impls` -> `&enum:impl-traits`
-   - Updated `%::` doc hint to reference `&tuple:impl-traits`.
-
-3. **debug macro fix**
-   - Fixed `wo-js-log` entry to define `wo-js-log` (not `w-js-log`).
-
-4. **symbol note consolidation**
-   - Appended symbol-resolution appendix into `drafts/runtime-traits-plan.md`.
-   - Removed duplicated `docs/symbol-spec.md` after migration.
-
-## Validation notes
-
-- Verified `wo-js-log` evaluates successfully.
-- Verified `&struct:impl-traits` resolves as runtime proc.
-- Confirmed old `&struct:with-impls` now reports unknown symbol (no compatibility layer, by design).
-
-## Follow-up
-
-- If needed, add explicit migration note/changelog entry for removed `*-with-impls` internal names.

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

@@ -1,91 +0,0 @@
-# 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-02-23-2321-ns-imports-code-fixes.md

@@ -1,42 +0,0 @@
-# 2026-0223 命名空间 imports 操作 Bug 修复
-
-## 背景
-
-通过在 `demos/calcit.cirru` 上逐一测试 `cr edit` 的 namespace 相关子命令，发现三处导致 Agent 频繁用错的根本原因。
-
-## 发现的 Bug
-
-### Bug 1：`imports --code 'rule'` 产生平坦结构，与 `extract_require_rules` 不兼容
-
-- **现象**：`imports --code '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 --code ':require ...'` 静默产生 `:require :require` 重复
-
-- **现象**：写 `:require respo.core :refer $ sym` 不报错，但生成 `ns my.ns :require :require respo.core ...`
-- **修复**：当 Cirru 解析后发现数组第一元素为 `:require` 字符串，立即返回错误消息，引导用户不包含 `:require` 前缀。
-
-### Bug 3：`add-ns --code 'ns WRONG_NAME ...'` 名称不一致静默通过
-
-- **现象**：`cr edit add-ns my.ns --code '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` 命令的 `--code` 输入格式：**不含 `:require` 前缀**，直接是规则体（`src-ns :refer $ sym`）。单条规则用 `--code`，多条规则用 `--file`（每行一条）或通过 stdin 传 JSON 数组（元素为数组）。
-- `add-import` 和 `imports` 的格式一致，都是 `src-ns :refer $ sym`（无 `:require` 前缀）。
-- `add-ns --code` 中若传完整 `ns` 表达式，内部名称必须与位置参数完全匹配。
-- 最佳实践：优先使用 `add-import`（带保护和覆盖控制），`imports` 只在需要全量重置时使用。

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

@@ -1,93 +0,0 @@
-# 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-02-25-0111-guidebook-no-check-block-upgrades.md

@@ -1,52 +0,0 @@
-# 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-02-25-0113-runtime-type-validation-and-macro-quoting.md

@@ -1,41 +0,0 @@
-# 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-02-25-1131-check-md-eval-improvements.md

@@ -1,13 +0,0 @@
-# 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-02-26-1324-check-md-inprocess-cache-and-path-labels.md

@@ -1,7 +0,0 @@
-# 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-02-27-1640-unify-markdown-readers.md

@@ -1,16 +0,0 @@
-# 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-02-27-1958-tree-rewrite-command-and-reference-model.md

@@ -1,18 +0,0 @@
-# 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/calcit.cirru`）：
-  - `tree replace` 可执行普通替换；
-  - `tree rewrite` 无 `--with` 会按预期报错；
-  - `tree rewrite` 携带 `--with` 可按预期执行。

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

@@ -1,29 +0,0 @@
-# 202602272200 — 新增 `edit split-def` 命令
-
-## 改动概要
-
-新增 `cr edit split-def <ns/def> --path <path> --name <new-name>` 命令，用于将某定义内指定路径的子表达式提取为同命名空间内的一个新定义，原位置替换为新定义的名字。
-
-## 修改文件
-
-- `src/cli_args.rs`：新增 `EditSplitDefCommand` struct（参数：`target`, `--path`, `--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> --path '' --code 'quote (defn new-name (args...) ...)'`。

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

@@ -1,33 +0,0 @@
-# 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> --path <child-path>`
-
-等价 Paredit `raise-sexp`。将指定子节点**整体替换掉其父节点**。
-
-- `path` 必须至少一个元素（才有父节点）
-- `parent_path = path[..n-1]`，用 `apply_operation_at_path(..., "replace", child)` 实现
-- 典型用途：去掉 `if` 只保留某分支、去掉 `let` 只保留最终返回值表达式
-
-### `cr tree wrap <ns/def> --path <path> --code '<template>'`
-
-等价 `cr tree rewrite ... --with 'self=.'`，但更简洁。模板中 `self` 自动绑定为原节点。
-
-- 适合"加一层调用"的常见模式：`wrap --code 'println self'`、`wrap --code 'let ((x self)) x'`
-- 当需要引用原节点的**子节点**（不只是整体）时，仍需用 `rewrite --with`
-
-## 知识点
-
-- 三个互相对应的操作：`wrap`（包裹）→ `unwrap`（所有子节点展开）→ `raise`（单子节点替换父）
-- `wrap` 与 `rewrite` 的关系：`wrap` = `rewrite` 固定了 `self=.` 的语法糖，降低常用操作的命令复杂度