@calcit/procs 0.11.7 → 0.12.0

package/editing-history/2026-0306-1416-core-macro-schema-migration.md

@@ -0,0 +1,20 @@
+## 概要
+
+本次提交继续推进 schema-first 迁移，聚焦 `src/cirru/calcit-core.cirru`，为核心宏入口补齐显式 `:schema`，在不改变运行逻辑的前提下提升静态信息覆盖率与一致性。
+
+## 关键改动
+
+- 补齐高频线程/控制宏 schema：`->`、`->>`、`<-`、`if-not`、`thread-as`、`thread-first`、`thread-last`、`;nil`、`:`。
+- 补齐构造/模式宏 schema：`list-match`、`record-match`、`record-with`、`tag-match`、`field-match`、`{}`。
+- 补齐内部宏入口 schema：`&case`、`&list-match-internal`、`&record-match-internal`、`&field-match-internal`。
+- 补齐工具/调试宏 schema：`[,]`、`[][]`、`\`、`\.`、`call-w-log`、`call-wo-log`、`js-object`、`w-log`、`w-js-log`、`with-cpu-time`、`with-gensyms`、`wo-log`、`wo-js-log`、`noted`。
+
+## 结果
+
+- `calcit-core` 中 `defmacro` 对应的 `:schema nil` 已清空。
+- 每批改动后均执行 `edit format` 与 `yarn check-all`，回归通过。
+
+## 经验
+
+- 采用“按语义分组小批次补齐 + 每批全量回归”策略，可在大文件中稳定推进迁移并快速定位异常。
+- 对宏统一使用 `:kind :macro` 与 `:args/:rest/:return` 结构，能减少后续工具链处理分支。

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

@@ -0,0 +1,63 @@
+# 2026-03-06 15:52 core schema + hint-fn 迁移批次
+
+## 背景
+
+本批次延续 schema-first 迁移：
+
+- 在 `src/cirru/calcit-core.cirru` 继续将 runtime 内建的 `:schema nil` 改为显式 schema。
+- 在 `calcit/` 测试目录中，将旧式 `hint-fn` 参数写法迁移为新写法。
+
+## 主要改动
+
+### 1) Core runtime schema 补齐（无行为改动）
+
+在 `src/cirru/calcit-core.cirru` 增补了多批低风险条目的 schema，覆盖例如：
+
+- 数学/比较/位运算：`cos`/`sin`/`sqrt`/`round`/`round?`/`floor`/`ceil`、`bit-*` 系列等
+- 字符串/解析/格式化：`split`/`split-lines`/`trim`/`parse-cirru*`/`format-cirru*`
+- IO 与环境：`read-file`/`write-file`/`get-env`/`generate-id!`
+- 运行时工具：`atom`/`add-watch`/`remove-watch`/`type-of`/`turn-*`/`fold*`/`range`/`recur`/`raise`/`quit!`
+
+原则：仅补 schema，不改运行时逻辑。
+
+### 2) 旧式 hint-fn 参数写法迁移
+
+在 `calcit/test-types-inference.cirru` 中，将旧写法：
+
+- `:args $ [] :number`
+
+迁移为新写法：
+
+- `:args $ [] (:: 'x :number)`
+
+并复查 `calcit/**` 下同模式，不再命中。
+
+## 验证
+
+每批次均执行：
+
+- `cargo run --bin cr -- demos/compact.cirru edit format`
+- `yarn check-all`
+
+结果均通过（尾部稳定为 `... and 24 files not changed.`）。
+
+## 备注
+
+- 当前提交聚合了本轮连续小批次迁移结果，便于后续按文件/功能继续清理剩余 `:schema nil`。
+
+## 增补（同批次续改）
+
+### 3) 移除 legacy hint-fn clause 兼容（改为直接报错）
+
+在 `src/runner/preprocess.rs` 中将旧语法兼容从 warning 升级为 hard error：
+
+- 不再接受 `hint-fn` 内 legacy clauses：`return-type` / `generics` / `type-vars`
+- 统一在 `preprocess_hint_fn` 阶段报 `Syntax` 错误，提示迁移到 schema map 形式
+- 删除旧的 `warn_on_legacy_hint_fn_syntax` 路径并同步测试
+
+### 4) 文档更新（docs + guidebook）
+
+同步更新示例与说明，避免继续传播旧写法：
+
+- `docs/CalcitAgent.md`：补充“legacy clause 会直接报错”，并将 `:args` 示例改为命名参数条目
+- `guidebook/docs/cirru-syntax.md`、`guidebook/docs/features/static-analysis.md`、`guidebook/docs/features/records.md`：统一 `hint-fn` 示例为 schema-map + `(:: 'arg <type>)` 形式

package/editing-history/2026-0306-1936-schema-normalization-and-preprocess-preload.md

@@ -0,0 +1,12 @@
+# 本次修改记录
+
+- 统一 schema 风格：清理 `:args` / `:rest` 中参数名，保留类型表达式，降低重复声明。
+- 预处理前置 schema：在 `preprocess_defn` 中优先注入 schema hint，再进行类型与返回值检查。
+- 程序装载增强：`program` 层为定义缓存并暴露 schema 查询能力。
+- 快照规范化：`snapshot` 序列化时统一去除 schema 的 `:name` 字段与命名参数注解。
+- 文档同步：更新 Agent 文档中 `hint-fn` / schema 写法示例到当前风格。
+
+## 验证
+
+- `cargo test` 通过。
+- `yarn check-all` 通过。

package/editing-history/2026-0307-0142-unit-type-and-builtin-schemas.md

@@ -0,0 +1,82 @@
+# 2026-0307-0142 `:unit` 类型 + 内建函数 schema 批量补全
+
+## 改动概要
+
+### 1. Rust 类型系统: `CalcitTypeAnnotation::Nil` (`:unit`)
+
+在 `src/calcit/type_annotation.rs` 中添加新的 `Nil` variant, 对应 Cirru 关键字 `:unit`。
+
+**使用场景**: 副作用函数 (side-effectful functions), 明确标注返回 `nil` 的情况, 区别于 `:dynamic` (未知类型)。
+
+**涉及改动点**:
+
+- `CalcitTypeAnnotation` enum: 新增 `Nil` variant
+- `builtin_type_from_tag_name`: `"unit" | "nil" => Self::Nil`
+- `builtin_tag_name`: `Self::Nil => Some("unit")`
+- `variant_order`: `Self::Nil => 27`
+- `matches_with_bindings`: `(Self::Nil, Self::Nil) => true`
+- `Hash impl`: `Self::Nil => "nil".hash(state)`
+- `value_matches_type_annotation`: `CalcitTypeAnnotation::Nil => matches!(value, Calcit::Nil)`
+- `gen_ir.rs`: `CalcitTypeAnnotation::Nil => type_tag_map("unit")`
+
+### 2. 副作用函数 `:return :unit` schema
+
+在 `src/cirru/calcit-core.cirru` 中为以下函数补充 `:return :unit` schema:
+
+| 函数名         | schema 要点                                             |
+| -------------- | ------------------------------------------------------- |
+| `each`         | `:args ([] :dynamic :fn) :return :unit`                 |
+| `write-file`   | `:args ([] :string :string) :return :unit`              |
+| `quit!`        | `:args ([] (:: :optional :number)) :return :unit`       |
+| `add-watch`    | `:args ([] :ref :dynamic :fn) :return :unit`            |
+| `remove-watch` | `:args ([] :ref :dynamic) :return :unit`                |
+| `reset!`       | `:generics 'T :args ([] (:: :ref 'T) 'T) :return :unit` |
+
+**注意事项**: 在 `:: :fn ('T) :unit` 中, `'T` 出现在 `('T)` 列表的算子位置会触发 EDN 解析错误 (`invalid operator for edn: 'T`)。对 `each` 的解决方案是简化成 `:fn`, 避免在 fn 参数类型中使用泛型变量作为算子。
+
+### 3. 内建函数 schema 批量补全 (54 条)
+
+对 `calcit-core.cirru` 中原本 `:schema nil` 的内建 primitive 函数批量补充类型:
+
+**`&list:*` (16 条)**: `assoc`, `assoc-after`, `assoc-before`, `concat`, `contains?`, `count`, `dissoc`, `distinct`, `empty?`, `first`, `includes?`, `nth`, `rest`, `reverse`, `slice`, `to-set`
+
+**`&map:*` (12 条)**: `assoc`, `common-keys`, `contains?`, `count`, `destruct`, `diff-keys`, `diff-new`, `dissoc`, `empty?`, `get`, `includes?`, `to-list`
+
+**`&str:*` (15 条)**: `compare`, `concat`, `contains?`, `count`, `empty?`, `escape`, `find-index`, `first`, `includes?`, `nth`, `pad-left`, `pad-right`, `replace`, `rest`, `slice`
+
+**集合操作 (10 条)**: `&difference`, `&exclude`, `&include`, `&set:count`, `&set:destruct`, `&set:empty?`, `&set:includes?`, `&set:intersection`, `&set:to-list`, `&union`
+
+**泛型模式** (使用 `'T` 非算子位置):
+
+```cirru
+{} (:kind :fn)
+  :generics $ [] 'T
+  :args $ [] (:: :list 'T) :number 'T
+  :return $ :: :list 'T
+```
+
+### 4. Clippy & 代码质量修复
+
+- `emit_js.rs`: 消除冗余闭包 `xs.iter().skip(1).any(schema_marks_async)`
+- `query.rs`: 添加复杂类型别名 `type RefResults = ...`
+
+## 技术知识点
+
+### `'T` 在 schema 文件中的限制
+
+- **可用位置**: `:generics $ [] 'T`, `(:: :list 'T)` 的末尾参数, `[] :arg1 'T`
+- **不可用位置**: `('T)` 即 `'T` 作为列表算子 (head), 例如 `(:: :fn ('T) :unit)` 中的 `('T)`
+- **根本原因**: schema 验证通过 `cirru_edn::parse` 进行, EDN 解析器要求列表头部必须是合法算子
+
+### `:unit` vs `:dynamic`
+
+- `:unit` — 明确标注 "此函数返回 nil, 且是预期行为" (副作用函数)
+- `:dynamic` — 未知/任意类型 (默认回退)
+
+## 验证结果
+
+```
+cargo clippy -- -D warnings  → ✓ 0 warnings
+cargo test                   → ✓ 17/17 passed
+yarn check-all               → ✓ took 571ms, all passed
+```

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

@@ -0,0 +1,32 @@
+# 2026-03-07 CalcitAgent.md 文档更新
+
+## 修改内容
+
+### 1. 新增 `--no-tips` 全局标志文档
+
+在「主要运行命令」小节中，`cr js --check-only` 之后新增：
+
+```
+- `cr --no-tips <subcommand> ...` - 隐藏所有编辑/查询命令输出的 "Tips:" 提示行（适合脚本/Agent 使用）
+  - 示例：`cr --no-tips demos/compact.cirru query def calcit.core/foldl`
+```
+
+**背景**：`aa21b3a` 提交新增了 `--no-tips` 全局开关（`TIPS_SUPPRESSED: AtomicBool`，通过 `suppress_tips()` 设置），文档中缺少记录。
+
+### 2. 新增 HOF 高阶函数回调类型检查说明
+
+在「类型标注与检查 → 3. 支持的类型标签」之后，`约定：动态类型标注…` 注释的下方新增章节：
+
+**高阶函数（HOF）回调类型检查：**  
+`foldl`、`sort`、`filter`、`find`、`find-index`、`filter-not`、`mapcat`、`group-by` 等内置 HOF 的回调参数已强制要求 `:fn` 类型，传入非函数值时预处理阶段会触发类型警告。附正/误示例。
+
+**背景**：`aa21b3a` 提交修复了以下两条路径的类型检查：
+
+- Cirru `defn` schema (`calcit-core.cirru`)：`filter-not`/`find`/`find-index`/`foldl`/`foldl'`/`foldl-compare`/`mapcat`/`group-by`/`sort` 的回调参数由 `:dynamic` 改为 `:fn`（部分带泛型注解）
+- `ProcTypeSignature` (`proc_name.rs`)：`Foldl`/`Sort`/`FoldlShortcut`/`FoldrShortcut` 的回调参数 `dynamic` → `some_fn()`/`optional_fn()`
+
+## 知识点
+
+- **文档中不需要描述 `ProTypeSignature` 实现细节**，面向 Agent 只需说明行为：哪些 HOF 要求 `:fn` 参数。
+- **`--no-tips` 定位**：全局开关，放在 subcommand 前；所有 `Tips::print()` 调用均受其控制。
+- CalcitAgent.md 未发现旧 `-s/--stdin` 残留，无需清理。

package/editing-history/2026-0307-1652-decouple-snapshot-schema-to-calcit-type.md

@@ -0,0 +1,112 @@
+# 2026-0307-1652 — 解耦 snapshot::CodeEntry.schema 为 Arc<CalcitTypeAnnotation>
+
+## 核心改动
+
+将整个项目中 `snapshot::CodeEntry.schema` 和 `program::ProgramDefEntry.schema` 的类型，从 `Option<Edn>` / `Option<Arc<CalcitFnTypeAnnotation>>` 统一迁移为 `Arc<CalcitTypeAnnotation>`。
+
+同时打破了 `type_annotation.rs → program → snapshot → calcit` 的循环依赖。
+
+---
+
+## 循环依赖的解法
+
+**原依赖链（错误）：**
+
+```
+snapshot → calcit::type_annotation → program → snapshot  ❌
+```
+
+**修复方案：** 在 `type_annotation.rs` 中用 `OnceLock<fn>` 注册 program 级别的 lookup 函数，由 `program.rs` 在 `extract_program_data` 时调用 `register_program_lookups` 完成注册：
+
+```rust
+type LookupFn = fn(&str, &str) -> Option<Calcit>;
+static LOOKUP_EVALED_DEF: OnceLock<LookupFn> = OnceLock::new();
+static LOOKUP_DEF_CODE: OnceLock<LookupFn> = OnceLock::new();
+
+pub fn register_program_lookups(evaled: LookupFn, code: LookupFn) {
+  let _ = LOOKUP_EVALED_DEF.set(evaled);
+  let _ = LOOKUP_DEF_CODE.set(code);
+}
+```
+
+---
+
+## 修改文件列表
+
+### `src/calcit/type_annotation.rs`
+
+- 移除 `use crate::program;` 导入
+- 新增 OnceLock 静态注册机制及 `register_program_lookups` 公开函数
+- 将 6 处 `program::lookup_*` 调用替换为本地 `lookup_evaled_def` / `lookup_def_code_registered`
+- 新增 `CalcitTypeAnnotation::to_type_edn(&self) -> Edn` 序列化方法
+- 新增 `calcit_type_to_edn(form: &Calcit) -> Edn` 私有辅助函数（Custom 类型回退）
+- 新增 `CalcitFnTypeAnnotation::to_schema_edn(&self) -> Edn`（输出完整 schema map）
+- 新增 `CalcitFnTypeAnnotation::to_schema_calcit(&self) -> Calcit`（用于 hint-fn 注入）
+- 修复 `Self::Struct/Enum` 序列化：使用 `Edn::Tag` 而非 `Edn::Symbol`（类型不同）
+
+### `src/calcit.rs`
+
+- 在 `pub use type_annotation::` 中新增 `register_program_lookups`
+
+### `src/program.rs`
+
+- `ProgramDefEntry.schema: Arc<CalcitTypeAnnotation>`（取代旧 `Option<Arc<CalcitFnTypeAnnotation>>`）
+- `extract_program_data` 首行调用 `calcit::register_program_lookups(...)`
+- `lookup_def_schema` 返回类型改为 `Arc<CalcitTypeAnnotation>`（不再返回 Option，缺省返回 `DYNAMIC_TYPE`）
+- `apply_code_changes` 中 `schema: DYNAMIC_TYPE.clone()` 取代 `None`
+
+### `src/snapshot.rs`
+
+- 移除 `CalcitFnTypeAnnotation` 从导入（已无直接使用）
+- 新增 `mod schema_serde`：将 `Arc<CalcitTypeAnnotation>` 序列化为 `Option<Edn>` 保持二进制 RMP 兼容
+- `CodeEntry.schema: Arc<CalcitTypeAnnotation>`，带 `#[serde(default, with = "schema_serde")]`
+- `TryFrom<Edn>` / `From` trait 实现全部更新，使用 `parse_fn_schema_from_edn` + `DYNAMIC_TYPE`
+- 测试用例中 `schema: Some(Edn)` 改为通过 `parse_fn_schema_from_edn` 构造 `Arc<CalcitTypeAnnotation>`
+
+### `src/detailed_snapshot.rs`
+
+- 同 `snapshot.rs` 模式：新增 `mod schema_serde`，字段类型改为 `Arc<CalcitTypeAnnotation>`
+- `From<CodeEntry>` / `From<DetailedCodeEntry>` 均直接 clone Arc
+
+### `src/runner/preprocess.rs`
+
+- hint-fn 注入改为先匹配 `CalcitTypeAnnotation::Fn(fn_annot)`，再调用 `fn_annot.to_schema_calcit()`
+
+### `src/bin/cli_handlers/edit.rs`
+
+- schema 清空时：`schema = DYNAMIC_TYPE.clone()`
+- schema 写入时：通过 `parse_fn_schema_from_edn` 解析后包装为 `Arc<CalcitTypeAnnotation::Fn(...)>`
+
+### `src/bin/cli_handlers/query.rs`
+
+- 4 处 `entry.schema.is_some()` / `if let Some(schema_edn)` 全部改为 `CalcitTypeAnnotation::Fn(fn_annot)` 匹配
+- 序列化时通过 `fn_annot.to_schema_edn()` 转回 Edn 后再调用 `schema_edn_to_cirru`
+
+### `src/bin/cr.rs`
+
+- 新增 `CalcitTypeAnnotation` 到 `use calcit::{calcit::{...}}` 导入
+- 原 `schema: None` 改为 `calcit::calcit::DYNAMIC_TYPE.clone()`
+- `if let Some(schema_edn)` 改为 `if let CalcitTypeAnnotation::Fn(fn_annot)`
+
+### `src/bin/cr_sync.rs`
+
+- `schema: None` 改为 `calcit::calcit::DYNAMIC_TYPE.clone()`
+
+---
+
+## 关键设计决策
+
+1. **`Arc<CalcitTypeAnnotation>` 永不为 None**：缺省值统一为 `DYNAMIC_TYPE`（全局 `LazyLock<Arc<CalcitTypeAnnotation>>` 单例），避免到处 `Option` 处理。
+
+2. **二进制兼容**：`schema_serde` 模块确保 `Dynamic` → 序列化为 `None`，`Fn(...)` → 序列化为完整 Edn map，与旧 `Option<Edn>` 格式一一对应。
+
+3. **`Edn::Tag` 用于类型名称**：`Struct`/`Enum` 类型序列化时用 `Edn::Tag(name)` 而非 `Edn::Symbol(name)`，因为 `EdnTag` 不能直接构造 `Edn::Symbol(Arc<str>)`。
+
+---
+
+## 验证结果
+
+- `cargo build` ✅
+- `cargo clippy -- -D warnings` ✅
+- `cargo test` ✅（17 passed）
+- `yarn check-all` ✅（515ms）

package/editing-history/2026-0307-1821-snapshot-schema-validation.md

@@ -0,0 +1,6 @@
+# 2026-0307-1821 Snapshot and Schema Serialization Refinement
+
+- Verified Rust core changes using `yarn try-rs`, `cargo test`, and `yarn check-all`.
+- Ensured `Snapshot` and `CodeEntry` serialization/deserialization remains consistent with the new direct map EDN format for schemas.
+- Confirmed unit tests for `CodeEntry` with examples and schema validation are passing.
+- Validated that `calcit-core.cirru` example parsing works as expected.

package/editing-history/2026-0307-1959-schema-def-kind-arity-validation.md

@@ -0,0 +1,96 @@
+# Schema vs Definition Kind/Arity Validation
+
+## Summary
+
+Added structural validation that compares a definition's code form against its schema declaration. This catch mismatches between declared schema metadata (`:kind`, arg count, rest param) and the actual `defn`/`defmacro` code at analysis time.
+
+## Key Changes
+
+### `src/calcit/type_annotation.rs`
+
+1. **Added `SchemaKind` enum** (`pub enum SchemaKind { Fn, Macro }`) — distinguishes `:kind :fn` from `:kind :macro` schemas.
+
+2. **Extended `CalcitFnTypeAnnotation`** with two new fields:
+   - `pub fn_kind: SchemaKind` — schema's declared kind (fn/macro).
+   - `pub rest_type: Option<Arc<CalcitTypeAnnotation>>` — schema's `:rest` type, if present.
+
+3. **`parse_fn_schema_from_edn`** — now reads `:kind :macro` → `SchemaKind::Macro` and `:rest` → `rest_type` from the EDN map.
+
+4. **`to_schema_edn`** — now serializes `fn_kind` (`fn`/`macro`) and `rest_type` (`:rest` key in the output map). Previously always emitted `:kind :fn` and omitted `:rest`.
+
+5. **All `CalcitFnTypeAnnotation` construction sites** updated to add `fn_kind: SchemaKind::Fn, rest_type: None` defaults (7 total).
+
+6. **`substitute_type_vars`** also propagates `fn_kind` and substitutes `rest_type`.
+
+### `src/calcit.rs`
+
+- `SchemaKind` added to the `pub use type_annotation::{ ... }` re-export.
+
+### `src/bin/cr.rs`
+
+1. **`SchemaKind` imported** in the `use calcit::calcit::{...}` block.
+
+2. **`TypeCoverageRow` struct** gained `schema_issues: Vec<String>` field — carries kind/arity mismatch warnings per definition.
+
+3. **`validate_def_vs_schema(ns, def_name, code, schema) -> Vec<String>`** — new function:
+   - `&runtime-inplementation` leaf → skip (builtin proc/syntax).
+   - Schema not `CalcitTypeAnnotation::Fn` → skip.
+   - Code head not `defn`/`defmacro` → skip.
+   - Schema `:kind :fn` + code `defmacro` → error.
+   - Schema `:kind :macro` + code `defn` → error.
+   - Required arg count mismatch → error.
+   - `has_rest` mismatch (schema `:rest` vs code `&`) → error.
+
+4. **`analyze_param_arity(args: Option<&Cirru>) -> (usize, bool)`** — helper that counts required params and detects the `&` rest marker in a `defn`/`defmacro` args list.
+
+5. **`analyze_code_entry`** calls `validate_def_vs_schema` to populate `schema_issues` on each `TypeCoverageRow`.
+
+6. **`run_check_types` output loop** prints a `schema-issues:` section for rows with non-empty issues.
+
+7. **10 new unit tests** covering:
+   - `&runtime-inplementation` skip
+   - Correct defn/macro → no issues
+   - Kind mismatch (`:fn` vs `defmacro`, `:macro` vs `defn`)
+   - Arity mismatch
+   - Rest param mismatch
+   - `analyze_param_arity` basics
+8. **`CR_DEBUG_SCHEMA` debug flag** — when `CR_DEBUG_SCHEMA=1`, prints per-entry schema kind debug info to stderr during `analyze check-types`.
+
+### `src/runner/preprocess.rs`
+
+1. **Runtime/preprocess enforcement added** — schema-vs-definition structural checks now run while preprocessing `defn`/`defmacro`, not only in `analyze check-types`.
+2. **`validate_def_schema_during_preprocess(...)`** — mirrors the `check-types` validation for `:kind`, required arity, and `:rest`, and raises a hard `[Type Error]` during normal execution paths such as `yarn try-rs`.
+3. **Schema hints preserved** — preprocess still injects `hint-fn`, but now only after the definition passes structural schema validation.
+4. **2 new preprocess tests** covering arity mismatch and `:kind` mismatch at preprocess time.
+
+### `calcit/test-hygienic.cirru`
+
+- Updated existing test fixture schemas so they match actual code:
+  - `add-11` / `add-11-safe`: `:kind :macro`
+  - `add-2`: arg schema corrected from 2 params to 1
+
+### `src/snapshot.rs`
+
+- **`test_macro_schema_round_trip`** — verifies `schema_cirru_to_edn` + `parse_fn_schema_from_edn` + `normalize_schema_edn` preserve `SchemaKind::Macro` end-to-end.
+- **`test_macro_schema_full_file_round_trip`** — verifies full `CodeEntry` serialize (`From<&CodeEntry> for Edn`) → `cirru_edn::format` → `cirru_edn::parse` → `TryFrom<Edn> for CodeEntry` round-trip preserves `fn_kind: Macro`.
+
+## Validation Rule Summary
+
+| Schema `:kind` | Code form                 | Result          |
+| -------------- | ------------------------- | --------------- |
+| `:fn`          | `defn`                    | ✓ ok            |
+| `:fn`          | `defmacro`                | ✗ kind mismatch |
+| `:macro`       | `defmacro`                | ✓ ok            |
+| `:macro`       | `defn`                    | ✗ kind mismatch |
+| any            | `&runtime-inplementation` | ✓ skip          |
+
+Arg count and rest param are checked independently of kind.
+
+## Notes
+
+- **`calcit.core` schemas require binary rebuild**: Schema edits to `src/cirru/calcit-core.cirru` do not take effect at runtime until the binary is rebuilt, because the core namespace is always loaded from the embedded `include_bytes!` snapshot produced by `build.rs`. Schema validation is most useful for user-defined namespaces.
+- **Normal execution now checks schemas too**: before this follow-up, schema-vs-def mismatches were only reported by `analyze check-types`; now they fail fast during normal preprocess/runtime startup as well.
+
+## Test Results
+
+All 125 tests pass (99 library + 26 binary), including 2 new snapshot round-trip tests and 2 new preprocess validation tests.

package/editing-history/2026-0307-migrate-hint-fn-to-schema.md

@@ -0,0 +1,29 @@
+# 2026-03-07 migrate hint-fn to schema for top-level defs
+
+## 背景
+
+`calcit-core.cirru` 中大量顶层函数在函数体内以 `hint-fn $ {} (:return ...)` 的方式标注返回类型。这是旧写法，新写法是在 `:schema` 字段中声明 `{} (:kind :fn) (:return ...)` 等结构。
+
+## 本次操作
+
+- 将所有顶层定义（`defn`/`defmacro`）的 `hint-fn` 从函数体 `[3,0]` 位置删除，改为 `edit schema` 写入 `:schema` 字段
+- 共处理 100+ 个函数，包含 `calcit.core` 和 `calcit.internal` 两个 namespace
+- 对带泛型的函数（`&list:filter`、`&list:map`、`&fn:bind` 等）补充了 `:generics` 字段
+
+## 保留 hint-fn 的情况
+
+内层/局部函数没有 schema 位置，仍然保留 hint-fn，例如：
+
+- `{,}` 内的 `&{,}` 局部函数
+- `map` 内的 `%map`
+- `join` 内的 `%join` / `%join-str`
+- `select-keys` 内的 `%select-keys`
+- `&map:filter` 等内部 defn
+
+## 修复的 bug
+
+- `parse_target` 在 `query.rs` / `edit.rs` 中使用 `rsplit_once('/')` 导致函数名含 `/`（如 `/`、`/=`）无法识别，改为 `split_once('/')` 修复
+
+## 验证
+
+`yarn try-rs` 全程通过，最终耗时约 350ms。

package/editing-history/2026-0307-remove-enum-prototype-field.md

@@ -0,0 +1,43 @@
+# 2026-0307 移除 CalcitEnum 的 prototype 字段
+
+## 背景
+
+老版本的 `CalcitEnum` 使用 `prototype: Arc<CalcitRecord>` 存储枚举定义（字段=variant tag，值=payload 类型列表），因为当时 enum 借助 record 的数据结构来定义。现在 enum 已有独立的定义语法（`defenum`），prototype 字段冗余，予以移除。
+
+## 主要变更
+
+### `src/calcit/sum_type.rs`
+
+- `CalcitEnum` 结构体：`prototype: Arc<CalcitRecord>` → `name: EdnTag`
+- `from_record` / `from_arc`：提取 name，不再存储整个 record
+- 删除 `prototype()` 方法，新增 `name()` 返回 `&EdnTag`
+- 新增 `to_record_prototype() -> CalcitRecord`：根据 `name + variants` 按需重建 `CalcitRecord`，供 `preprocess.rs` 向后兼容使用
+
+### `src/calcit.rs`
+
+- `Hash` 实现：改为对 variant tag + payload type 逐项哈希
+- `PartialEq` 实现：`a.prototype() == b.prototype()` → `a.name() == b.name() && a.variants() == b.variants()`
+
+### `src/calcit/compare.rs`
+
+- `compare_calcit_enum_values`：不再对比 prototype record，改为先比较 name，再逐 variant 比较 tag 和 payload types（深度比较），确保 `Ord::cmp == Equal` ⟺ `PartialEq::eq == true`
+
+### `src/data.rs`
+
+- `Enum(enum_def)` 序列化分支：通过 `enum_def.name()` 和 `enum_def.variants()` 直接读取，不再依赖 prototype record
+
+### `src/runner/preprocess.rs`
+
+- `resolve_record_value` 中所有 `Calcit::Enum(enum_def)` 分支：`enum_def.prototype().to_owned()` → `enum_def.to_record_prototype()`
+
+## 验证结果
+
+- `cargo build` ✅（无警告）
+- `cargo test` ✅（94 + 17 = 111 通过，0 失败）
+- `cargo clippy -- -D warnings` ✅（无警告）
+- `yarn check-all` ✅（exit 0）
+
+## 踩坑与注意
+
+- `compare_calcit_enum_values` 最初只比 tag 未比 payload types，导致 `cmp_equal_matches_eq_for_complex_named_variants` 失败。修复时需对每个 variant 的 payload types 也做深度比较。
+- `to_record_prototype()` 是按需重建而非缓存，性能上无问题（仅在类型检查预处理阶段调用）。

package/editing-history/2026-0307-schema-args-type-enforcement.md

@@ -0,0 +1,66 @@
+# 2026-03-07 schema.args 类型检查接通与 fn 类型注解修复
+
+## 背景
+
+上一次 session（commit a008f8b）为 calcit-core 的 54+ 函数添加了 `:schema` 中的 `:args` 字段。但发现这些 schema
+并未实际触发调用现场的类型检查——`CalcitFn.arg_types` 只从函数体的 `assert-type` 扫描，从未读取 schema `:args`。
+
+## 根因分析
+
+类型检查数据流：
+
+```
+calcit-core.cirru :schema :args
+  → preprocess.rs 注入为 (HintFn schema_value) 进 defn 体
+  → syntax.rs defn 调用 detect_arg_type_hints → collect_arg_type_hints_from_body
+  → 只扫描 assert-type/assert-traits，忽略 HintFn！
+  → CalcitFn.arg_types 对 schema-only 函数全为 Dynamic
+  → check_user_fn_arg_types 提前返回，无任何检查
+```
+
+## 修复内容
+
+### 1. 接通 schema.args → CalcitFn.arg_types（`syntax.rs` + `type_annotation.rs`）
+
+- 新增 `CalcitTypeAnnotation::extract_arg_types_from_hint_form(form, params)` 方法
+- 新增 `parse_schema_args_types` 和 `is_args_list_head` 辅助方法
+- `syntax.rs:defn` 中优先从 hint-fn（schema 注入）提取 arg_types，再回退到 assert-type 扫描
+
+### 2. fn 类型注解解析修复（`type_annotation.rs`）
+
+发现 `(:: :fn ([] 'T 'U) (:: 'T 'U) 'T)` 格式的 fn 类型注解被错误解析，因为 `[]` 头部（list constructor proc）
+出现在 args 列表中被当作普通类型处理：
+
+- **三处** `parse_type_annotation_form` `:fn` 分支：args_form 为 List 时跳过 `[]` 头部
+- **`parse_generics_list`**：跳过 `[]` 头部，使 `([] 'T 'U)` 作为合法 generics 列表（`'T 'U` 不能作 Cirru EDN operator）
+- **`matches_signature`**：移除 generics 数量检查，改用 `matches_with_bindings` 解析 TypeVar 绑定（使具体函数类型能匹配泛型签名）
+- **`matches_with_bindings`**：`Tag` 可满足 `DynFn`/`Fn` 约束（Calcit 中 `:tag` 作为 map key accessor 可调用）
+
+### 3. method 调用类型检查修复（`preprocess.rs`）
+
+方法调用的 arg 类型检查循环中缺少对 `Variadic` 的处理，导致 `.union s1 s2` 误报。修复为与 `check_user_fn_arg_types` 一致的 Variadic 处理。
+
+### 4. calcit-core.cirru schema 修正
+
+| 函数            | 修正内容                                                                          |
+| --------------- | --------------------------------------------------------------------------------- |
+| `every?`        | `:args $ (:: :list :dynamic)` → `:dynamic`（接受 set）                            |
+| `keys`          | `:args $ :map` → `:dynamic`（接受 record）                                        |
+| `merge`         | `:args $ :map` + `:rest $ :map` → `:dynamic`（接受 record）                       |
+| `merge-non-nil` | 同上                                                                              |
+| `reduce`        | fn-arg 格式 `([] 'T 'U)(:: 'T 'U)` → `([] 'T 'U)([] 'T 'U)`（正确 generics+args） |
+| `map`           | fn-arg 格式 `([] 'T 'U)(:: 'T)` → `([] 'T 'U)([] 'T)`（正确 generics+1-arg）      |
+
+## 验证
+
+- `each ([] 1 2 3) 42` → 正确警告（42 不是 :fn）
+- `reduce ([] 1 2 3) 0 &+` → 无误报（&+ 满足 fn(T,U)->T）
+- `cargo test`：92 passed, 0 failed（之前 1 个失败的 test_examples_field_parsing 也通过了）
+- `yarn check-all`：全量集成测试通过，0 warnings
+
+## 关键知识点
+
+- `([] 'T 'U)` 是合法 Cirru EDN（`[]` 是合法 operator），`('T 'U)` 不合法（`'T` 不能作 operator）
+- fn 类型 generics 列表格式：`([] 'T 'U)` 跳过 `[]` 头后得到 `[T, U]`
+- fn 类型 args 列表格式：`([] :number :number)` 跳过 `[]` 头后得到 `[:number, :number]`
+- `matches_signature` 不应检查 generics 数量——调用方传入的具体函数不声明 generics，但 TypeVar 绑定会在 args 匹配时解析

package/editing-history/2026-0308-0031-schema-generics-quote-normalization.md

@@ -0,0 +1,35 @@
+# Schema Generics Quote Normalization
+
+## Summary
+
+Tightened schema loading so legacy generic symbols stored with embedded leading quotes now fail immediately, then normalized existing `calcit-core.cirru` schema generics from `''T`-style output to the correct `'T` source syntax.
+
+## Key Changes
+
+- `src/calcit/type_annotation.rs`
+  - Stopped serializing schema generics as `Edn::Symbol("'T")`.
+  - Now writes plain EDN symbols like `Edn::Symbol("T")`, which format back to source as `'T`.
+  - Keeps compatibility when parsing previously saved legacy symbols, but normalizes them to plain names.
+
+- `src/snapshot.rs`
+  - Added load-time rejection for legacy schema generic symbols carrying embedded leading quotes.
+  - Normalized schema EDN → Cirru conversion to go through format+parse so quoted symbols render correctly.
+  - Added regression tests for:
+    - single-quote round-trip,
+    - rejecting legacy quoted EDN symbols on load,
+    - rejecting `''T` on schema writes.
+
+- `build.rs`
+  - Added the same legacy-generic rejection during build-time loading of `src/cirru/calcit-core.cirru`, so bad schema data fails `yarn check-all` immediately.
+
+- `src/cirru/calcit-core.cirru`
+  - Replaced all legacy schema generic forms like `''T`, `''A`, `''K` with correct single-quoted forms.
+
+- `docs/CalcitAgent.md`
+  - Updated schema/type-annotation guidance to reflect schema-first top-level typing and correct generic syntax examples.
+
+## Validation
+
+- `cargo fmt`
+- `cargo test schema_ -- --nocapture`
+- `yarn check-all`

package/editing-history/2026-0308-1905-schema-typeref-and-assert-migration.md

@@ -0,0 +1,34 @@
+# 本次修改记录
+
+## 主题
+
+- 完善 schema 类型系统：区分泛型变量与命名类型引用，支持 `'Result` 一类类型引用在 schema 中稳定往返。
+- 继续推进 schema-first 迁移：清理 `calcit-core` 与若干测试文件中的 `assert-type`，将约束收敛到 `:schema` 与局部 `hint-fn`。
+- 强化诊断：改进运行时参数个数错误与构建期 schema 解析报错，方便定位问题。
+
+## 主要改动
+
+### 1) Rust 侧类型系统收紧
+
+- 在 `src/calcit/type_annotation.rs` 中新增命名类型引用分支，并让解析、匹配、显示、序列化都感知泛型作用域。
+- `src/builtins/syntax.rs` 与 `src/builtins/records.rs` 改为按泛型上下文解析 schema，避免把命名类型误判成 type var。
+- `src/codegen/gen_ir.rs`、`src/snapshot.rs` 同步适配新 schema 结构与 round-trip 测试。
+
+### 2) schema / hint-fn 迁移
+
+- `src/cirru/calcit-core.cirru` 中移除剩余 `assert-type` 调用点，改为顶层 `:schema` 或局部 `hint-fn`。
+- `calcit/test.cirru`、`calcit/debug/check-args.cirru`、`calcit/test-fn.cirru`、`calcit/test-types.cirru` 改用更精细的函数签名与局部约束。
+- 修正函数类型直写 schema 的参数形式，统一使用 `([] ...)` 表达参数列表。
+
+### 3) 错误信息增强
+
+- `src/runner.rs` 在参数个数不匹配时生成结构化报错，而不是直接触发内部 panic。
+- `build.rs` 对 schema EDN 解析错误增加截断与整理，避免输出过长、难以定位。
+
+## 验证
+
+- `cargo fmt` 通过。
+- `cargo clippy -- -D warnings` 通过。
+- `yarn compile` 通过。
+- `cargo test` 通过。
+- `yarn check-all` 通过。