@calcit/procs 0.12.34 → 0.12.36

package/README.md

@@ -12,11 +12,17 @@ Core design:
 
 - Interpreter runs on Rust, extensible with Rust FFI
 - Persistent Data Structure
-- Structural Editor(with indentation-based syntax as a fallback)
+- Indentation-based Cirru syntax, friendly to plain text editing
 - Lisp macros, functional style
 - Compiles to JavaScript in ES Modules, JavaScript Interop
 - Hot code swapping friendly
 
+Current direction:
+
+- `calcit.cirru` is the primary source snapshot; legacy `compact.cirru` is still compatible
+- CLI-first development with `cr` and `caps`, designed to work well with AI agents in terminal workflows
+- Better CLI editing and validation for CI, docs lookup, module management, and incremental updates
+
 ### Install ![GitHub Release](https://img.shields.io/github/v/release/calcit-lang/calcit)
 
 Build and install with Rust:
@@ -29,12 +35,12 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 cargo install calcit
 ```
 
-4 binaries are installed:
+Installed binaries:
 
 - `calcit`, the runtime and js compiler
 - `cr-wasm`, standalone WASM codegen tool
 - `caps`, for downloading dependencies declared in `deps.cirru`
-- `bundle_calcit`, bundle code if you don't want to use Calcit Editor
+- `bundle_calcit`, bundle code for distribution
 
 When installing from source, explicitly include both runners:
 
@@ -44,9 +50,9 @@ cargo install --path . --bin cr --bin cr-wasm --bin caps --bin bundle_calcit
 
 To use Calcit in GitHub Actions, try [setup-cr](https://github.com/calcit-lang/setup-cr).
 
-### Usage
+### Quick Start
 
-Snippets evaluating:
+Evaluate snippets:
 
 ```bash
 cr eval 'range 100'
@@ -54,23 +60,24 @@ cr eval 'range 100'
 cr eval 'thread-first 100 range (map $ \ * % %)'
 ```
 
-Run with a [compact.cirru](https://github.com/calcit-lang/lilac/blob/main/compact.cirru):
+Run with a runtime snapshot such as `calcit.cirru` (legacy filename: `compact.cirru`):
 
 ```bash
-cr compact.cirru # run once (default)
+cr calcit.cirru # run once (default)
+cr compact.cirru # legacy filename still works
 
-cr # by default, it picks `compact.cirru`
+cr # by default, it picks `calcit.cirru`, then falls back to `compact.cirru`
 
 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,
+By default Calcit reads `:init-fn` and `:reload-fn` from `calcit.cirru` configs (falling back to `compact.cirru`). You may also specify functions:
 
 ```bash
 cr --init-fn='app.main/main!' --reload-fn='app.main/reload!'
 ```
 
-and even configure `:entries` in `compact.cirru`:
+You may also configure `:entries` in `calcit.cirru`:
 
 ```bash
 cr --entry server
@@ -78,10 +85,10 @@ cr --entry server
 
 ### JavaScript codegen
 
-It compiles to JavaScript and runs in consistet semantics. However it might require a lot of JavaScript interop.
+Calcit compiles to JavaScript with consistent semantics. In browser or Node projects, JavaScript interop is still expected.
 
 ```bash
-cr js # compile to js, also picks `compact.cirru` by default
+cr js # compile to js, also picks `calcit.cirru` by default
 cr js --emit-path=out/ # compile to js and save in `out/`
 ```
 
@@ -92,40 +99,28 @@ import { main_$x_, reload_$x_ } from "./js-out/app.main.mjs";
 main_$x_(); // which corresponds to `main!` function in calcit
 ```
 
-### Calcit Editor & Bundler
-
-Install [Calcit Editor](https://github.com/calcit-lang/editor) and run `ct` to launch editor server,
-which writes `compact.cirru` and `.compact-inc.cirru` on saving. Try launching example by cloning [Calcit Workflow](https://github.com/calcit-lang/calcit-workflow).
-
-Read more in [Minimal Calcit](https://github.com/calcit-lang/minimal-calcit/blob/main/README.md) to learn how to code Calcit with a plain text editor.
-
-Read more in [Respo Calcit Workflow](https://github.com/calcit-lang/respo-calcit-workflow) to learn to create an MVC webpage with [Respo](http://respo-mvc.org/).
-
-### MCP (Model Context Protocol) Support
-
-Calcit provides MCP server functionality for integration with AI assistants and development tools. The MCP server offers tools for:
+### CLI and Agent Workflow
 
-- **Code Management**: Read, write, and modify Calcit namespaces and definitions
-- **Project Operations**: Manage modules, dependencies, and configurations
-- **Calcit Runner**: Start/stop background runner processes with incremental updates
-- **Documentation**: Query API docs, reference materials, and dependency documentation
+The recommended workflow is plain text editing plus CLI validation, often driven by an AI agent in terminal.
 
-#### Incremental File Processing
+Common commands:
 
-When using the Calcit Runner through MCP:
-
-1. **Start Runner**: Use `start_calcit_runner` to launch the background process. This automatically:
-   - Creates a `.calcit-tmp/` directory
-   - Copies the current `compact.cirru` as a temporary baseline
+```bash
+cr docs agents --full   # read the current agent workflow guide
+cr query search 'foo'   # locate code by symbol or string
+cr edit ...             # structured edits for defs, imports, config, modules
+cr js                   # compile once
+cr js -w                # watch mode
+caps                    # install/update dependencies from deps.cirru
+```
 
-2. **Generate Incremental Updates**: After making changes to your code, use `generate_calcit_incremental` to:
-   - Compare current `compact.cirru` with the temporary baseline
-   - Generate a `.compact-inc.cirru` file with only the changes
-   - Apply incremental updates to the running process
+Calcit Editor is no longer the recommended path for everyday development. If you still need the older editor workflow, see [Calcit Editor](https://github.com/calcit-lang/editor).
 
-3. **Check Results**: After generating the incremental file, always check the runner logs using `grab_calcit_runner_logs` to verify that updates were applied successfully.
+Related examples and workflows:
 
-This workflow enables efficient hot-reloading during development without restarting the entire application.
+- [Minimal Calcit](https://github.com/calcit-lang/minimal-calcit/blob/main/README.md)
+- [Respo Calcit Workflow](https://github.com/calcit-lang/respo-calcit-workflow)
+- [setup-cr](https://github.com/calcit-lang/setup-cr) for GitHub Actions
 
 ### Modules
 
@@ -141,23 +136,23 @@ This workflow enables efficient hot-reloading during development without restart
 
 Run `caps` to download. Sources are downloaded into `~/.config/calcit/modules/`. If a module contains `build.sh`, it will be executed mostly for compiling Rust dylibs.
 
-`:calcit-version` helps in check version, and provides hints in [CI](https://github.com/calcit-lang/setup-cr) environment.
+`:calcit-version` helps with version checks and provides hints in [CI](https://github.com/calcit-lang/setup-cr).
 
-To load modules, use `:modules` configuration and `compact.cirru`(which normally generated from `calcit.cirru`):
+To load modules, use `:modules` configuration and the runtime snapshot file `calcit.cirru` (legacy: `compact.cirru`):
 
 ```cirru
 :configs $ {}
-  :modules $ [] |memof/compact.cirru |lilac/
+  :modules $ [] |memof/calcit.cirru |lilac/
 ```
 
 Paths defined in `:modules` field are just loaded as files from `~/.config/calcit/modules/`,
-i.e. `~/.config/calcit/modules/memof/compact.cirru`.
+i.e. `~/.config/calcit/modules/memof/calcit.cirru`.
 
-Modules that ends with `/`s are automatically suffixed `compact.cirru` since it's the default entry.
+Modules ending with `/` are automatically suffixed with `calcit.cirru`, and still fall back to `compact.cirru` for compatibility.
 
 ### Development
 
-I use these commands to run local examples:
+Local validation commands:
 
 ```bash
 # run tests in Rust
@@ -169,13 +164,23 @@ cargo run --bin cr -- calcit/test.cirru js && yarn try-js
 # run snippet
 cargo run --bin cr -- eval 'range 100'
 
-cr compact.cirru ir # compiles intermediate representation into program-ir.cirru
+cr calcit.cirru ir # compiles intermediate representation into program-ir.cirru
 
 cr-wasm calcit/test-wasm.cirru # compile standalone wasm target to js-out/program.wasm
 ```
 
+For repository development, the usual validation flow is:
+
+```bash
+cargo fmt
+cargo clippy -- -D warnings
+yarn compile
+cargo test
+yarn check-all
+```
+
 - [Cirru Parser](https://github.com/Cirru/parser.rs) for indentation-based syntax parsing.
-- [Cirru EDN](https://github.com/Cirru/cirru-edn.rs) for `compact.cirru` file parsing.
+- [Cirru EDN](https://github.com/Cirru/cirru-edn.rs) for runtime snapshot file parsing (`calcit.cirru` / legacy `compact.cirru`).
 - [Ternary Tree](https://github.com/calcit-lang/ternary-tree.rs) for immutable list data structure.
 
 Other tools:

package/{rfc → RFCs}/03-05-function-schema-dual-track-rfc.md

@@ -28,8 +28,8 @@
       :args $ [] 'T :number
       :rest :number
       :return $ :: :tuple :ok 'U
-      :where $ []
-        :: 'Eq 'T
+      :where $ {}
+        'T Eq
 ```
 
 说明：
@@ -83,20 +83,19 @@
 
 ## `:where` 约束
 
-约束统一放在 `:where`，每条约束是一条 tuple：
+约束统一放在 `:where` map，key 是泛型变量，value 是单个 trait 或 trait 列表：
 
 ```cirru
-[]
-  :: 'Eq 'T
-  :: 'Show 'T
-  :: 'Ord 'U
+{}
+  'T $ [] Eq Show
+  'U Ord
 ```
 
 约定：
 
-- 同一变量多条约束表示“且”；
-- 顺序不影响语义；
-- 若当前没有约束，直接写 `:where $ []`。
+- 同一变量多个约束放在同一个 value 列表里，表示“且”；
+- map 项顺序不影响语义；
+- 若当前没有约束，直接省略 `:where`，或写空 map `:where $ {}`。
 
 ## parse 校验示例
 
@@ -105,13 +104,13 @@
 主示例：
 
 ```bash
-cr demos/compact.cirru cirru parse-edn "(:: :fn ({} (:generics ([] 'T 'U)) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U)) (:where ([] (:: 'Eq 'T)))))"
+cr demos/calcit.cirru cirru parse-edn "(:: :fn ({} (:generics ([] 'T 'U)) (:where ({} ('T Eq))) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U))))"
 ```
 
 运行时数据验证：
 
 ```bash
-cr demos/compact.cirru eval "let ((schema (:: :fn ({} (:generics ([] 'T 'U)) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U)) (:where ([] (:: 'Eq 'T))))))) (println schema) (println (type-of schema)) , schema"
+cr demos/calcit.cirru eval "let ((schema (:: :fn ({} (:generics ([] 'T 'U)) (:where ({} ('T Eq))) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U)))))) (println schema) (println (type-of schema)) , schema"
 ```
 
 ## 顶层定义与局部定义的分工

package/RFCs/05-12-program-diff-rfc.md

@@ -0,0 +1,204 @@
+# RFC: `cr analyze program-diff <GIT REF>`
+
+状态：Draft
+日期：2026-05-12
+
+---
+
+## 1. 概要
+
+新增命令：
+
+- `cr analyze program-diff <GIT REF>`
+
+该命令从 Git 中读取指定版本的完整运行时快照文件（默认沿用当前 `cr` 的输入文件路径，优先 `calcit.cirru`，兼容旧文件名 `compact.cirru`），确保**历史版本**与**当前工作区版本**都能被正确解析为 Calcit snapshot，然后做**结构化 diff**。
+
+输出目标不是纯文本行 diff，而是面向程序结构的树形 diff：
+
+- 顶层展示 `package/configs/entries/files` 等结构；
+- 文件层展示 `ns/defs`；
+- definition 层展示 `doc/schema/examples/code`；
+- `code/examples/ns.code` 内部继续深入到 Cirru 表达式节点级别；
+- 无变化分支允许灰色折叠；
+- 变更分支默认展开；
+- 增加、删除、修改分别用不同符号和颜色表示。
+
+## 2. 动机
+
+当前针对运行时快照文件的版本对比主要依赖 Git 行 diff，但它有几个明显问题：
+
+1. **对结构不友好**：`calcit.cirru`（兼容旧文件名 `compact.cirru`）是机器生成的 snapshot，行 diff 容易受格式、字段顺序和长表达式影响；
+2. **对表达式内部变化不友好**：definition 代码改动往往是局部子树变化，行 diff 很难快速看出 AST 层面的增删改；
+3. **对 LLM / CLI 阅读不友好**：调用 `git diff` 后很难一眼区分“只是某个 def 变了”还是“整个 namespace 被搬动了”；
+4. **缺少 parse guard**：历史版本文件如果本身损坏，应该先明确报解析失败，而不是直接进入错误 diff。
+
+因此需要一个基于 Calcit 自身 snapshot/Cirru 结构的 diff 命令。
+
+## 3. 命令定义
+
+```/dev/null/rfc.txt#L1-2
+cr analyze program-diff <GIT REF>
+```
+
+语义：
+
+- `<GIT REF>` 可以是 `HEAD~1`、tag、branch、commit SHA 等；
+- 当前侧使用 `cr` 输入路径（默认优先 `calcit.cirru`，兼容旧文件名 `compact.cirru`）；
+- 历史侧使用 `git show <ref>:<repo-relative-input-path>` 读取文件内容；
+- 两边都必须先经过：
+  1. `cirru_edn::parse`
+  2. `snapshot::load_snapshot_data`
+- 任一侧失败都直接返回错误并停止 diff。
+
+## 4. 输出设计
+
+### 4.1 总体结构
+
+输出分 2 段：
+
+1. Summary
+2. Tree Diff
+
+Summary 示例：
+
+```/dev/null/rfc.txt#L1-6
+# Program Diff
+- ref: HEAD~1
+- file: calcit.cirru
+- parsed: ok / ok
+- changes: ~12 +3 -1
+```
+
+### 4.2 树形 diff 约定
+
+参考 `cr analyze call-graph` 的树形展示风格，继续使用：
+
+- `├──`
+- `└──`
+- `│`
+
+在此基础上增加状态符号：
+
+- `=` unchanged（灰色）
+- `~` modified（黄色）
+- `+` added（绿色）
+- `-` removed（红色）
+
+### 4.3 折叠策略
+
+- `Unchanged` 子树默认只显示一行概要，并灰色折叠；
+- `Modified` / `Added` / `Removed` 子树默认展开；
+- root 总是展开；
+- 叶子节点直接显示 old/new 摘要。
+
+### 4.4 表达式内部 diff
+
+对于 `code/examples/ns.code` 内部的 `Cirru`：
+
+- 叶子变更显示 old/new；
+- list 节点按子节点序列做结构化比对；
+- 插入/删除节点要保留索引位置和节点摘要；
+- 同位置替换优先显示为 `modified`，而不是简单拆成 delete+add；
+- 整棵新增/删除表达式应继续展开其子结构。
+
+## 5. 范围
+
+本次只在 `calcit` 当前仓库内实现，不先抽到 `cirru_parser`：
+
+- 先满足 CLI 工作流；
+- diff 数据结构先放在当前项目中，便于快速迭代；
+- 后续如果算法稳定，再考虑抽取成 Cirru parser / edn 侧通用模块。
+
+## 6. 实现方案
+
+### 6.1 新模块
+
+新增库模块：
+
+- `src/program_diff.rs`
+
+职责：
+
+1. 读取当前 snapshot 文件；
+2. 从 git ref 读取历史 snapshot 文件；
+3. 校验两边都能 parse/load；
+4. 构建结构化 diff tree；
+5. 生成适合终端的彩色树形输出。
+
+### 6.2 CLI 接入
+
+- `src/cli_args.rs`
+  - 为 `AnalyzeSubcommand` 增加 `ProgramDiff`；
+- `src/bin/cr.rs`
+  - 将该命令作为 standalone analyze 命令优先处理；
+- `src/bin/cli_handlers/command_echo.rs`
+  - 增加 command echo 渲染；
+- `src/bin/cli_handlers/mod.rs`
+  - 导出 handler。
+
+### 6.3 Git 文件读取
+
+流程：
+
+1. 用 `git rev-parse --show-toplevel` 找 repo root；
+2. 将当前 `input` 解析成 repo-relative path；
+3. 用 `git show <ref>:<relative-path>` 读取历史内容；
+4. 若文件不存在、ref 不存在、或命令失败，则直接返回错误。
+
+### 6.4 Diff 层级
+
+优先按 snapshot 语义层比较：
+
+1. `package`
+2. `about`
+3. `configs`
+4. `entries`
+5. `files`
+6. `file.ns`
+7. `file.defs`
+8. `def.doc`
+9. `def.schema`
+10. `def.examples`
+11. `def.code`
+12. `Cirru` 子树
+
+这样可以避免直接把整个运行时快照文件当作匿名 EDN 树来比，输出会更稳定、更可读。
+
+### 6.5 Cirru 序列 diff
+
+list 内部子节点对比采用“带替换代价的序列对齐”策略：
+
+- 完全相等 => `match`
+- 不相等但对位更合理 => `replace`
+- 仅旧侧存在 => `remove`
+- 仅新侧存在 => `insert`
+
+这比单纯按索引逐位比较更适合表达式中间插入/删除节点的场景。
+
+## 7. 预期收益
+
+- 更适合 review `calcit.cirru`（兼容旧文件名 `compact.cirru`）的语义变化；
+- 更容易理解大型 definition 的局部 AST 改动；
+- 对 agent/LLM 更友好，能直接拿到层级化变化；
+- 为后续抽象成 Cirru diff 模块提供实现样本。
+
+## 8. 暂不处理
+
+本 RFC 本轮不覆盖：
+
+- 三方 merge；
+- patch 应用；
+- HTML/TUI 交互界面；
+- 抽取到 `cirru_parser` crate；
+- 和 `cr tree show` / `cr query def` 的统一 chunk/diff UI。
+
+## 9. 后续可能扩展
+
+后续可考虑继续增加：
+
+- `--format json`
+- `--no-color`
+- `--expand-all`
+- `--only <path-prefix>`
+- `--git-path <path>`（脱离当前 input）
+- 将 Cirru diff 算法下沉到 parser 层

package/RFCs/05-31-generic-where-bounds-mfs.md

@@ -0,0 +1,124 @@
+# 泛型 `:where` 约束 MFS
+
+日期：2026-05-31
+
+状态：Draft
+
+## 目标
+
+在现有函数 schema 泛型链路上，增加最小可用的 trait 约束能力：
+
+- schema / `hint-fn` 可以声明 `:where`；
+- 调用点在泛型变量完成绑定后，检查绑定结果是否满足 trait 约束；
+- 先走主链路，不引入完整 trait solver，不处理复杂的 transitive requires 推导。
+
+## 当前实现边界
+
+本轮只覆盖：
+
+- `CalcitFnTypeAnnotation` 的 `:where` 解析与序列化；
+- 顶层 `:schema` 注入 `hint-fn` 后，用户函数调用的 `:where` 检查；
+- 局部函数 / 期望函数类型场景的 `:where` 检查；
+- trait 约束当前以 preprocess warning 形式暴露。
+
+本轮不覆盖：
+
+- trait `requires` 的递归满足性；
+- 约束失败直接升级为 hard error；
+- 基于 `:where` 的代码生成优化；
+- 复杂多态分派或 impl 搜索策略调整。
+
+## Canonical Cirru EDN 形态
+
+### 顶层 wrapped schema
+
+`CodeEntry.:schema` 在 snapshot / Cirru EDN 里的推荐形态：
+
+```cirru
+%{} :CodeEntry
+  :doc |demo
+  :code $ quote
+    defn show-it (x)
+      .show x
+  :examples $ []
+  :schema $ :: :fn
+    {}
+      :generics $ [] 'T
+      :where $ {}
+        'T Show
+      :args $ [] 'T
+      :return :string
+```
+
+### 多 trait 约束
+
+单个类型变量绑定多个 trait 时，值是一个列表：
+
+```cirru
+:: :fn $ {}
+  :generics $ [] 'T 'U
+  :where $ {}
+    'T $ [] Show Eq
+    'U Ord
+  :args $ [] 'T 'U
+  :return 'T
+```
+
+### 一行 Cirru EDN 示例
+
+```cirru
+(:: :fn ({} (:generics ([] 'T 'U)) (:where ({} ('T ([] Show Eq)) ('U Ord))) (:args ([] 'T 'U)) (:return 'T)))
+```
+
+## 约束格式结论
+
+`:`where` 当前使用 map，而不是 list-of-tuples。这一点刻意对齐 Rust `where` 的分离式设计：泛型名字继续放在 `:generics`，trait 约束单独放在 `:where`，避免把“变量声明”和“约束条件”混在同一个位置里。
+
+- key: 泛型变量，例如 `'T`
+- value: 单个 trait，或 `[]` 列表中的多个 trait
+
+也就是：
+
+```cirru
+:where $ {}
+  'T Show
+  'U $ [] Eq Ord
+```
+
+不要写成旧草案里的 tuple 形式。`:: 'Show 'T` / `:: 'Eq 'U` 这类写法已经废弃，不应再出现在任何新文档、示例或测试输入里。
+
+后者不要再作为新文档示例。
+
+在概念上可以把它理解成 Rust 里的：
+
+- `fn f<T, U>(...) where T: Show + Eq, U: Ord`
+- 在 Calcit 中对应为 `:generics $ [] 'T 'U` 与 `:where $ {} 'T $ [] Show Eq  'U Ord`
+
+## 与 EDN / 内部表示的关系
+
+- Cirru 文本里写 `'T`；
+- 进入 EDN 后，它仍然是 symbol，只是内部不会把前导 `'` 作为名字的一部分存储；
+- trait 名称在 schema 里直接写定义名，例如 `Show`、`Eq`，不加 `:` 前缀。
+
+## 主链路开发步骤
+
+1. 文档先固定 canonical `:where` 形态，避免继续沿用旧 tuple 草案。
+2. schema parse / serialize 支持 `:where`。
+3. 用户函数与局部函数调用，在泛型绑定后做 trait 约束检查。
+4. 增加 parse / roundtrip / warning 级别测试。
+5. 视结果决定是否把 warning 升级成 error，并是否纳入 trait `requires`。
+
+## 当前测试最小集
+
+至少保留以下方向：
+
+- `hint-fn` 里的 `:where` 能被提取；
+- 顶层 schema roundtrip 后 `:where` 不丢失；
+- 满足 trait 约束时无 warning；
+- 不满足 trait 约束时出现明确 warning。
+
+## 下一步
+
+- 先把 `03-05-function-schema-dual-track-rfc.md` 中旧的 `:where` tuple 示例替换掉；
+- 再补 schema roundtrip 测试，确保文档与实际输出一致；
+- 之后再决定是否把约束失败升级为 `E_GENERIC_WHERE_BOUND_MISMATCH`。

package/{rfc → RFCs}/README.md

@@ -26,6 +26,7 @@
 | `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` 约束的最小功能规格，先作为主链路开发基线。 |
 
 ## 已执行的清理
 

package/build.rs

@@ -1,4 +1,4 @@
-use cirru_edn::{Edn, EdnRecordView, from_edn};
+use cirru_edn::{Edn, EdnMapView, EdnRecordView, from_edn};
 use cirru_parser::Cirru;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
@@ -102,6 +102,56 @@ fn map_key_path_segment(key: &Edn) -> String {
   }
 }
 
+fn canonical_schema_field_name(text: &str) -> Option<&'static str> {
+  match text.trim_start_matches(':') {
+    "kind" => Some("kind"),
+    "args" => Some("args"),
+    "return" => Some("return"),
+    "rest" => Some("rest"),
+    "generics" => Some("generics"),
+    "where" => Some("where"),
+    _ => None,
+  }
+}
+
+fn canonical_schema_kind_name(text: &str) -> Option<&'static str> {
+  match text.trim_start_matches(':') {
+    "fn" => Some("fn"),
+    "macro" => Some("macro"),
+    _ => None,
+  }
+}
+
+fn normalize_schema_map(map: &EdnMapView) -> Edn {
+  let mut normalized = EdnMapView::default();
+
+  for (key, value) in &map.0 {
+    let normalized_key = match key {
+      Edn::Tag(tag) => Edn::tag(tag.ref_str()),
+      Edn::Str(text) => canonical_schema_field_name(text.as_ref())
+        .map(Edn::tag)
+        .unwrap_or_else(|| key.clone()),
+      Edn::Symbol(text) => canonical_schema_field_name(text.as_ref())
+        .map(Edn::tag)
+        .unwrap_or_else(|| key.clone()),
+      _ => key.clone(),
+    };
+
+    let normalized_value = match (&normalized_key, value) {
+      (Edn::Tag(tag), Edn::Str(text)) | (Edn::Tag(tag), Edn::Symbol(text)) if tag.ref_str() == "kind" => {
+        canonical_schema_kind_name(text.as_ref())
+          .map(Edn::tag)
+          .unwrap_or_else(|| value.clone())
+      }
+      _ => value.clone(),
+    };
+
+    normalized.insert(normalized_key, normalized_value);
+  }
+
+  Edn::Map(normalized)
+}
+
 /// Convert a schema Edn value (either old Quote-wrapped or new direct map) into Edn map form.
 fn parse_schema_from_edn(value: &Edn, owner: &str) -> Result<Edn, String> {
   // Simple scalar schemas (e.g. :dynamic, :nil) are valid as-is — skip Cirru path
@@ -110,6 +160,29 @@ fn parse_schema_from_edn(value: &Edn, owner: &str) -> Result<Edn, String> {
       validate_schema_edn_no_legacy_quotes(value, owner)?;
       return Ok(value.clone());
     }
+    Edn::Map(map) => {
+      let normalized = normalize_schema_map(map);
+      validate_schema_edn_no_legacy_quotes(&normalized, owner)?;
+      return Ok(normalized);
+    }
+    Edn::Tuple(view)
+      if matches!(view.tag.as_ref(), Edn::Tag(tag) if matches!(tag.ref_str(), "fn" | "macro"))
+        && matches!(view.extra.first(), Some(Edn::Map(_))) =>
+    {
+      let Some(Edn::Map(map)) = view.extra.first() else {
+        unreachable!();
+      };
+      let mut normalized = match normalize_schema_map(map) {
+        Edn::Map(map) => map,
+        _ => unreachable!(),
+      };
+      if normalized.tag_get("kind").is_none() && matches!(view.tag.as_ref(), Edn::Tag(tag) if tag.ref_str() == "macro") {
+        normalized.insert_key("kind", Edn::tag("macro"));
+      }
+      let normalized = Edn::Map(normalized);
+      validate_schema_edn_no_legacy_quotes(&normalized, owner)?;
+      return Ok(normalized);
+    }
     _ => {}
   }
   // Old format: Edn::Quote wrapping Cirru — convert to direct map Edn

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

@@ -2,7 +2,7 @@
 
 ## 背景
 
-通过在 `demos/compact.cirru` 上逐一测试 `cr edit` 的 namespace 相关子命令，发现三处导致 Agent 频繁用错的根本原因。
+通过在 `demos/calcit.cirru` 上逐一测试 `cr edit` 的 namespace 相关子命令，发现三处导致 Agent 频繁用错的根本原因。
 
 ## 发现的 Bug
 

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

@@ -12,7 +12,7 @@
 - `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`）：
+- 真实命令验证（基于 `demos/calcit.cirru`）：
   - `tree replace` 可执行普通替换；
   - `tree rewrite` 无 `--with` 会按预期报错；
   - `tree rewrite` 携带 `--with` 可按预期执行。

package/editing-history/2026-0304-1548-impl-new-dot-method-input-and-doc-hints.md

@@ -27,7 +27,7 @@
 - `yarn compile`
 - `cargo test`
 - `yarn check-all`
-- `cargo run --bin cr -- demos/compact.cirru query examples 'calcit.core/&impl::new'`
-- `cargo run --bin cr -- demos/compact.cirru query examples 'calcit.core/&impl:get'`
+- `cargo run --bin cr -- demos/calcit.cirru query examples 'calcit.core/&impl::new'`
+- `cargo run --bin cr -- demos/calcit.cirru query examples 'calcit.core/&impl:get'`
 
 以上在本次改动后均通过。

package/editing-history/2026-0306-1552-core-schema-and-hintfn-migration.md

@@ -36,7 +36,7 @@
 
 每批次均执行：
 
-- `cargo run --bin cr -- demos/compact.cirru edit format`
+- `cargo run --bin cr -- demos/calcit.cirru edit format`
 - `yarn check-all`
 
 结果均通过（尾部稳定为 `... and 24 files not changed.`）。

package/editing-history/2026-0307-1302-calcit-agent-docs-update.md

@@ -8,7 +8,7 @@
 
 ```
 - `cr --no-tips <subcommand> ...` - 隐藏所有编辑/查询命令输出的 "Tips:" 提示行（适合脚本/Agent 使用）
-  - 示例：`cr --no-tips demos/compact.cirru query def calcit.core/foldl`
+  - 示例：`cr --no-tips demos/calcit.cirru query def calcit.core/foldl`
 ```
 
 **背景**：`aa21b3a` 提交新增了 `--no-tips` 全局开关（`TIPS_SUPPRESSED: AtomicBool`，通过 `suppress_tips()` 设置），文档中缺少记录。

package/editing-history/2026-0320-1229-query-window-3-with-parent-preview.md

@@ -56,17 +56,17 @@
 ## 验证
 
 - `cargo check --bin cr` 通过。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query find --help`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query find --help`
   - 可见 `--detail-offset` 参数。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search --help`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search --help`
   - `--start-path` 示例为点号格式。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 5`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 5`
   - 输出降噪，路径为点号，窗口外压缩。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 0`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 0`
   - 详情窗口为 `[0, 3)`，每条命中仅展示一行（优先父节点预览）。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
   - 精确命中不再把 `states` 视觉误判为 `state`；且不显示“add --exact”提示。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search-expr state -f respo.app.comp.todolist/comp-todolist --detail-offset 0`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search-expr state -f respo.app.comp.todolist/comp-todolist --detail-offset 0`
   - 输出样式一致（单行预览）。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/compact.cirru query search-expr state -f respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search-expr state -f respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
   - 结果为 `No matches found`，符合结构精确匹配预期。

package/editing-history/2026-0323-1137-command-echo-tool-output-cleanup.md

@@ -62,8 +62,8 @@
 - `cargo run --bin cr -- calcit/test.cirru query find render`
 - `cargo run --bin cr -- calcit/test.cirru tree show app.main/test-json -p ''`
 - `cargo run --bin cr -- calcit/test.cirru docs search chunk -f agent-advanced.md`
-- `cargo run --bin cr -- demos/compact.cirru docs check-md docs/CalcitAgent.md`
-- `cargo run --bin cr -- /tmp/calcit-cli-demo/compact.cirru tree replace ...` 多次人工检查 replace 输出形态
+- `cargo run --bin cr -- demos/calcit.cirru docs check-md docs/CalcitAgent.md`
+- `cargo run --bin cr -- /tmp/calcit-cli-demo/calcit.cirru tree replace ...` 多次人工检查 replace 输出形态
 
 ## 经验
 

package/editing-history/2026-0410-0011-snapshot-empty-version-pipe-marker.md

@@ -2,7 +2,7 @@
 
 ## 背景
 
-PR `snapshot-format` 新增了空 `configs.version` 的回归测试，但 GitHub Actions 上加载 `compact.cirru` 时，`(:version ||)` 会解析成字符串 `"|"`，没有命中原先仅检查空白字符串的校验。
+PR `snapshot-format` 新增了空 `configs.version` 的回归测试，但 GitHub Actions 上加载运行时快照文件（`calcit.cirru` / legacy `compact.cirru`）时，`(:version ||)` 会解析成字符串 `"|"`，没有命中原先仅检查空白字符串的校验。
 
 ## 知识点
 

package/editing-history/2026-0526-0957-match-docs-check-md.md

@@ -0,0 +1,24 @@
+# 2026-05-26 match 文档与 check-md 校验
+
+## 修改内容
+
+- 将 `match` 的文档说明统一为同时适用于 enum tuple 和 plain tuple，不再把 `tag-match` 描述成 plain tuple 的唯一入口。
+- 更新 `features/enums.md`、`features/tuples.md`、`features/common-patterns.md`、`features.md`、`quick-reference.md`、`run/agent-advanced.md` 中的推荐表述与示例。
+- 为 `agent-advanced.md` 里无法独立运行的 DOM / 事件示意片段补上 `cirru.no-check`，使 `cr docs check-md` 只校验可执行代码块。
+
+## 验证
+
+- `cargo run --bin cr -- eval $'match (:: :point 10 20)\n  (:point x y) (+ x y)\n  _ 0'`
+- `cargo run --bin cr -- docs check-md docs/features.md`
+- `cargo run --bin cr -- docs check-md docs/features/common-patterns.md`
+- `cargo run --bin cr -- docs check-md docs/features/enums.md`
+- `cargo run --bin cr -- docs check-md docs/features/error-handling.md`
+- `cargo run --bin cr -- docs check-md docs/features/traits.md`
+- `cargo run --bin cr -- docs check-md docs/features/tuples.md`
+- `cargo run --bin cr -- docs check-md docs/quick-reference.md`
+- `cargo run --bin cr -- docs check-md docs/run/agent-advanced.md`
+
+## 知识点
+
+- 原生 `match` 可以直接匹配 plain tuple；它不只适用于带 `defenum` 类型信息的 tuple。
+- 文档里的示意片段如果依赖 DOM helper、事件桥接函数或其他未加载上下文，应优先标记为 `cirru.no-check`，否则会被 `check-md` 的 `eval` 阻断。

package/editing-history/2026-0601-0003-update-callback-field-specialization.md

@@ -0,0 +1,19 @@
+# 2026-06-01 00:03 update callback field specialization
+
+## Summary
+
+- specialized `calcit.core/update` call checking so the 3rd callback arg can inherit a known record/struct field type instead of always staying at generic `fn('T) -> 'T`
+- fixed record field inference to resolve `TypeRef`-based struct annotations, not only direct `Record`/`Struct` annotations
+- aligned native `not` proc signature with calcit-core semantics by accepting dynamic input and returning `:bool`
+
+## Why
+
+- `respo` used precise type refs like `'respo.app.schema/Task`, but `infer_record_field_type` only looked through direct `Record`/`Struct` annotations, so `update task :done? not` could not see the field type
+- even after specializing `update`, Rust-side proc metadata still described `not` as `fn(:bool?) -> :bool`, which was stricter and inconsistent with the core schema/docs path
+
+## Validation
+
+- `cargo test specialize_update_uses_record_field_type_for_callback`
+- `cargo run --manifest-path /Users/chenyong/repo/calcit-lang/calcit/Cargo.toml --bin cr -- js` from `respo`
+- `yarn try-rs`
+- `cargo test`

package/editing-history/2026-0601-0005-release-0.12.36.md

@@ -0,0 +1,16 @@
+# 2026-06-01 00:05 release 0.12.36
+
+## Summary
+
+- bumped crate and npm package version from `0.12.35` to `0.12.36`
+- kept `ts-src/package.json` aligned with the root npm package metadata
+- prepared the workspace for a release lockfile refresh and tag creation
+
+## Why
+
+- this release publishes the `update` callback specialization and `not` proc typing fix after the PR checks passed
+- keeping repeated package metadata in sync avoids mismatched npm publish/version outputs during future packaging steps
+
+## Validation
+
+- `cargo update --workspace`

package/editing-history/202604182041-cr-wasm-split-and-runtime-stability.md

@@ -11,7 +11,7 @@
 
 ## 经验与注意事项
 
-- 对 `compact.cirru` 的修改必须通过 `cr edit`/`cr tree` 完成，避免文本直接编辑破坏结构。
+- 对运行时快照文件（`calcit.cirru` / legacy `compact.cirru`）的修改必须通过 `cr edit`/`cr tree` 完成，避免文本直接编辑破坏结构。
 - 在多项目联动（calcit + recollect）场景下，发布前验证至少应覆盖：
   - calcit: `yarn check-all`
   - recollect: `yarn test:cr`、`yarn test:js`、`yarn test:wasm`

package/editing-history/202605210055-tree-show-cr-config-and-edit-cleanup.md

@@ -0,0 +1,81 @@
+# 202605210055 — tree show 可选路径 + cr config 顶级命令 + cr edit 清理
+
+## 修改概要
+
+### 1. `cr tree show` — `-p` 参数改为可选，缺失时警告而非报错
+
+**动机**: Agent 调用 `cr tree show ns/def` 时若忘记 `-p`，原来直接报错导致 token 浪费。
+
+**变更文件**:
+
+- `src/cli_args.rs`: `TreeShowCommand.path` 类型从 `String` → `Option<String>`，doc 注释更新
+- `src/bin/cli_handlers/tree.rs`: `handle_show` 中对 `None` 输出黄色 `[Warn]`，默认使用空路径（root）
+- `src/bin/cli_handlers/command_echo.rs`: `push_tree` Show 分支改用 `opt "path"` 宏处理 Option 类型
+
+**效果**:
+
+```
+$ cr calcit.cirru tree show "ns/def"
+[Warn] No path (-p) specified; showing from root. Use -p '0' to start from a child node.
+Type: list (4 items)
+...
+```
+
+---
+
+### 2. `cr config` — 顶级配置管理命令
+
+**动机**: `cr query config`、`cr query modules`、`cr edit config`、`cr edit add-module`、`cr edit rm-module` 分散在不同子命令下，操作配置需要记忆多个入口。新增统一入口 `cr config`。
+
+**新命令**:
+| 命令 | 等价旧命令 |
+|---|---|
+| `cr config show` | `cr query config` |
+| `cr config modules` | `cr query modules` |
+| `cr config version [value]` | `cr edit config version ...` |
+| `cr config set <key> <value>` | `cr edit config <key> <value>` |
+| `cr config add-module <path>` | `cr edit add-module <path>` |
+| `cr config rm-module <path>` | `cr edit rm-module <path>` |
+
+`cr config version` 可独立使用（无参数显示当前版本，传 `patch/minor/major` 递增，传 semver 直接设置）。
+
+**变更文件**:
+
+- `src/cli_args.rs`: 添加 `CalcitCommand::Config`、`ConfigCommand`、`ConfigSubcommand`（含 `ConfigVersionCommand`）及各子命令 struct
+- `src/bin/cli_handlers/config.rs`: 新建，实现 `handle_config_command` 及各子命令处理函数（含 `handle_version`）
+- `src/bin/cli_handlers/edit.rs`: `parse_semver_value`、`bump_semver_value` 改为 `pub(crate)`
+- `src/bin/cli_handlers/mod.rs`: 注册 `mod config` 并 re-export `handle_config_command`
+- `src/bin/cli_handlers/command_echo.rs`: 添加 `config_name`、`push_config`，并在 `should_echo_command` / `render_command_echo` 中处理 `Config` 变体
+- `src/bin/cr.rs`: 添加 `CalcitCommand::Config` 分支
+
+---
+
+### 3. `cr edit` 清理 — 移除已迁移至 `cr config` 的子命令
+
+**动机**: `cr edit add-module`、`cr edit rm-module`、`cr edit config` 与新增的 `cr config` 重复，保持单一职责。
+
+**删除内容**:
+
+- `EditSubcommand::AddModule / RmModule / Config` 及对应 struct（`cli_args.rs`）
+- `handle_add_module / handle_rm_module / handle_config` 函数体（`edit.rs`）
+- `command_echo.rs` 中 `edit_name` 和 `push_edit` 两处 match 的三个变体
+
+**保留**（被 `config.rs` 和单元测试引用）:
+
+- `pub(crate) fn parse_semver_value` — semver 字符串解析
+- `pub(crate) fn bump_semver_value` — patch/minor/major 递增
+
+**文档更新**:
+
+- `docs/run/agent-advanced.md` "模块和配置" 章节、快速参考示例 → 全部改为 `cr config` 命令
+- `docs/CalcitAgent.md` 第 9 节"cr 能力地图" → 新增"配置管理"条目
+
+---
+
+## 知识点
+
+- `argh` 中将 `#[argh(option)]` 字段类型改为 `Option<T>` 可使该选项变为可选
+- `pub(crate)` 可在同一 crate 内跨模块共享；被其他模块引用时，不能因删除调用方而一并删除
+- 新增顶级命令时需同步更新 `command_echo.rs` 的三处：`should_echo_command`、`render_command_echo`（名称映射和 token push）
+- 移除 enum 变体时，需同时检查 `command_echo.rs` 的两处 match（`edit_name` 和 `push_edit`）
+- 单元测试也会引用函数，删除前要 grep `tests` 模块确认

package/editing-history/202605312052-macro-schema-roundtrip-and-weak-types.md

@@ -0,0 +1,6 @@
+- refined weak-types reporting in `cr analyze weak-types` to classify schema/code hits with detail paths
+- tightened builtin proc signatures for list/map/set/buf-list helpers toward generic compound types
+- kept `field-match` / `record-match` macro schema inputs precise in `calcit-core` while preserving round-trip behavior
+- fixed macro schema serialization to keep non-dynamic returns like `:record` instead of dropping them during snapshot save/load
+- aligned bare marker tag parsing for `:record` and related special tags with schema normalization behavior
+- updated docs and parser tests to current wrapped schema / guidebook-loading behavior

package/editing-history/202605312059-ci-docs-test-and-fn-helper-tightening.md

@@ -0,0 +1,3 @@
+- fixed docs query test to be stable both with and without ~/.config/calcit/docs configured, matching CI runner behavior
+- tightened calcit.core fn helper schemas for &fn:apply / &fn:bind / &fn:map to reduce nested schema-dynamic usage
+- validated with focused docs test, full cargo test, runtime cr calcit/test.cirru, weak-types analyze, and yarn check-all

package/editing-history/202605312105-map-generic-weak-types-followup.md

@@ -0,0 +1,5 @@
+- tightened multiple calcit.core snapshot schemas that safely remove weak composite internals without narrowing runtime behavior: typed path lists for `assoc-in`/`get-in`/`dissoc-in`/`update-in`/`contains-in?`, typed collection helpers like `apply`, `join-str`, `foldr-shortcut`, and explicit output map generics for `map-kv` and `pairs-map`
+- corrected one weak-types false lead by changing `keys` from returning `:list` to `:set`, matching runtime/tests and moving that hit out of the list family
+- extended `cr analyze weak-types` to classify nested schema-dynamic shapes/families, include per-definition summaries, split family/shape counts by `arg`/`return` position, and show per-definition `shape@position` contributors for the remaining hotspots
+- confirmed the current lower-bound weak hits under the existing type system: `&record:to-map` for heterogeneous record values; `&tuple:params`, `&cirru-quote:to-list`, `parse-cirru-list`, `&format-ternary-tree`, `&list:flatten`, `format-cirru`, and `format-cirru-one-liner` for mixed list payloads that cannot be soundly collapsed to `list<'T>`
+- verified the final baseline at schema-dynamic=290 with `cargo test --bin cr analyze_weak_types -- --nocapture`, repeated `cargo run --bin cr -- calcit/test.cirru analyze weak-types --ns calcit.core --only schema-dynamic`, and runtime suite checks via `cargo run --bin cr -- calcit/test.cirru`

package/lib/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.34",
+    "version": "0.12.36",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
-        "@types/node": "^25.0.9",
-        "typescript": "^6.0.2"
+        "@types/node": "^25.7.0",
+        "typescript": "^6.0.3"
     },
     "scripts": {
         "compile": "rm -rf lib && tsc",

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.34",
+  "version": "0.12.36",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
-    "@types/node": "^25.0.9",
-    "typescript": "^6.0.2"
+    "@types/node": "^25.7.0",
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "compile": "rm -rf lib && tsc",