@calcit/procs 0.11.8 → 0.12.0

package/.gitattributes

@@ -3,4 +3,4 @@ calcit.cirru -diff linguist-generated
 yarn.lock -diff linguist-generated
 Cargo.lock -diff linguist-generated
 lib -diff linguist-generated
-editing-history -diff linguist-generated
+editing-history/* -diff linguist-generated

package/build.rs

@@ -1,4 +1,4 @@
-use cirru_edn::{Edn, from_edn};
+use cirru_edn::{Edn, EdnRecordView, from_edn};
 use cirru_parser::Cirru;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
@@ -24,6 +24,8 @@ pub struct CodeEntry {
   #[serde(default)]
   pub examples: Vec<Cirru>,
   pub code: Cirru,
+  #[serde(default)]
+  pub schema: Option<Edn>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@@ -41,34 +43,250 @@ pub struct Snapshot {
   pub files: HashMap<String, FileInSnapShot>,
 }
 
+fn format_edn_preview(value: &Edn) -> String {
+  let raw = cirru_edn::format(value, true).unwrap_or_else(|_| format!("{value:?}"));
+  const LIMIT: usize = 220;
+  if raw.chars().count() > LIMIT {
+    let truncated = raw.chars().take(LIMIT).collect::<String>();
+    format!("{truncated}…")
+  } else {
+    raw
+  }
+}
+
+fn truncate_preview(raw: &str, limit: usize) -> String {
+  if raw.chars().count() > limit {
+    let truncated = raw.chars().take(limit).collect::<String>();
+    format!("{truncated}…")
+  } else {
+    raw.to_owned()
+  }
+}
+
+fn truncate_edn_error_nodes(message: &str) -> String {
+  const NODE_LIMIT: usize = 200;
+
+  message
+    .lines()
+    .map(|line| {
+      if let Some((prefix, preview)) = line.split_once("Node: ") {
+        format!("{prefix}Node: {}", truncate_preview(preview, NODE_LIMIT))
+      } else {
+        line.to_owned()
+      }
+    })
+    .collect::<Vec<_>>()
+    .join("\n")
+}
+
+fn format_edn_error<E: std::fmt::Display>(error: E) -> String {
+  truncate_edn_error_nodes(&error.to_string())
+}
+
+fn schema_path_label(path: &[String]) -> String {
+  if path.is_empty() { "<root>".to_owned() } else { path.join("") }
+}
+
+fn map_key_path_segment(key: &Edn) -> String {
+  match key {
+    Edn::Tag(tag) => format!(".{}", tag.ref_str()),
+    Edn::Str(text) => format!(".{text}"),
+    Edn::Symbol(text) => format!(".{text}"),
+    _ => ".<key>".to_owned(),
+  }
+}
+
+/// 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> {
+  // Old format: Edn::Quote wrapping Cirru — convert to direct map Edn
+  if let Ok(cirru) = from_edn::<Cirru>(value.clone()) {
+    let text = cirru_parser::format(&[cirru], true.into())
+      .map_err(|e| format!("{owner}: failed to format quoted schema before validation: {}", format_edn_error(e)))?;
+    let parsed = cirru_edn::parse(&text).map_err(|e| {
+      format!(
+        "{owner}: failed to parse quoted schema after formatting: {}; schema={}",
+        format_edn_error(e),
+        truncate_preview(&text, 200)
+      )
+    })?;
+    validate_schema_edn_no_legacy_quotes(&parsed, owner)?;
+    return Ok(parsed);
+  }
+  // New format: already a direct Edn map
+  validate_schema_edn_no_legacy_quotes(value, owner)?;
+  Ok(value.clone())
+}
+
+fn validate_schema_edn_no_legacy_quotes(value: &Edn, owner: &str) -> Result<(), String> {
+  fn walk(value: &Edn, owner: &str, path: &mut Vec<String>) -> Result<(), String> {
+    match value {
+      Edn::Symbol(s) => {
+        if s.starts_with('\'') {
+          let inner = s.trim_start_matches('\'');
+          return Err(format!(
+            "{owner}: invalid schema generic symbol `{s}` at {}. Use source syntax like `'{inner}`, but store it as plain EDN symbol `{inner}`.",
+            schema_path_label(path)
+          ));
+        }
+        Ok(())
+      }
+      Edn::List(xs) => {
+        for (idx, item) in xs.0.iter().enumerate() {
+          path.push(format!("[{idx}]"));
+          walk(item, owner, path)?;
+          path.pop();
+        }
+        Ok(())
+      }
+      Edn::Map(map) => {
+        for (k, v) in &map.0 {
+          path.push(map_key_path_segment(k));
+          walk(v, owner, path)?;
+          path.pop();
+        }
+        Ok(())
+      }
+      Edn::Tuple(view) => {
+        path.push(".tag".to_owned());
+        walk(view.tag.as_ref(), owner, path)?;
+        path.pop();
+        for (idx, item) in view.extra.iter().enumerate() {
+          path.push(format!("[{idx}]"));
+          walk(item, owner, path)?;
+          path.pop();
+        }
+        Ok(())
+      }
+      Edn::Set(set) => {
+        for (idx, item) in set.0.iter().enumerate() {
+          path.push(format!("[#{idx}]"));
+          walk(item, owner, path)?;
+          path.pop();
+        }
+        Ok(())
+      }
+      Edn::Record(_) => Ok(()),
+      _ => Ok(()),
+    }
+  }
+
+  let mut path = vec![];
+  walk(value, owner, &mut path)
+}
+
+fn parse_code_entry(edn: Edn, owner: &str) -> Result<CodeEntry, String> {
+  let record: EdnRecordView = match edn {
+    Edn::Record(r) => r,
+    other => return Err(format!("{owner}: expected CodeEntry record, got {}", format_edn_preview(&other))),
+  };
+  let mut doc = String::new();
+  let mut examples: Vec<Cirru> = vec![];
+  let mut code: Option<Cirru> = None;
+  let mut schema: Option<Edn> = None;
+  for (key, value) in &record.pairs {
+    match key.arc_str().as_ref() {
+      "doc" => doc = from_edn(value.clone()).map_err(|e| format!("{owner}: invalid `:doc`: {e}"))?,
+      "examples" => examples = from_edn(value.clone()).map_err(|e| format!("{owner}: invalid `:examples`: {e}"))?,
+      "code" => code = Some(from_edn(value.clone()).map_err(|e| format!("{owner}: invalid `:code`: {e}"))?),
+      "schema" => {
+        if !matches!(value, Edn::Nil) {
+          schema = Some(parse_schema_from_edn(value, owner).map_err(|e| format!("{owner}: invalid `:schema`: {e}"))?);
+        }
+      }
+      _ => {}
+    }
+  }
+  Ok(CodeEntry {
+    doc,
+    examples,
+    code: code.ok_or_else(|| format!("{owner}: missing `:code` field in CodeEntry"))?,
+    schema,
+  })
+}
+
+fn parse_file_in_snapshot(edn: Edn, file_name: &str) -> Result<FileInSnapShot, String> {
+  let record: EdnRecordView = match edn {
+    Edn::Record(r) => r,
+    other => {
+      return Err(format!(
+        "{file_name}: expected FileEntry record, got {}",
+        format_edn_preview(&other)
+      ));
+    }
+  };
+  let mut ns: Option<CodeEntry> = None;
+  let mut defs: HashMap<String, CodeEntry> = HashMap::new();
+  for (key, value) in &record.pairs {
+    match key.arc_str().as_ref() {
+      "ns" => ns = Some(parse_code_entry(value.clone(), &format!("{file_name}/:ns"))?),
+      "defs" => {
+        let map = match value {
+          Edn::Map(m) => m,
+          other => return Err(format!("{file_name}: expected `:defs` map, got {}", format_edn_preview(other))),
+        };
+        for (def_key, def_value) in &map.0 {
+          let name: String = from_edn(def_key.clone()).map_err(|e| format!("{file_name}: invalid def key: {e}"))?;
+          let owner = format!("{file_name}/{name}");
+          defs.insert(name, parse_code_entry(def_value.clone(), &owner)?);
+        }
+      }
+      _ => {}
+    }
+  }
+  Ok(FileInSnapShot {
+    ns: ns.ok_or_else(|| format!("{file_name}: missing `:ns` field in FileEntry"))?,
+    defs,
+  })
+}
+
+fn parse_files(edn: Edn) -> Result<HashMap<String, FileInSnapShot>, String> {
+  match edn {
+    Edn::Map(map) => {
+      let mut result = HashMap::with_capacity(map.0.len());
+      for (key, value) in map.0 {
+        let name: String = from_edn(key).map_err(|e| format!("invalid file key: {e}"))?;
+        result.insert(name.clone(), parse_file_in_snapshot(value, &name)?);
+      }
+      Ok(result)
+    }
+    other => Err(format!("snapshot `:files` must be a map, got {}", format_edn_preview(&other))),
+  }
+}
+
 fn main() {
   println!("cargo:rerun-if-changed=src/cirru/calcit-core.cirru");
 
   let out_dir = env::var_os("OUT_DIR").unwrap();
   let dest_path = Path::new(&out_dir).join("calcit-core.rmp");
 
-  let core_content = fs::read_to_string("src/cirru/calcit-core.cirru").expect("read core");
-  let core_data = cirru_edn::parse(&core_content).expect("parse core");
+  let core_content =
+    fs::read_to_string("src/cirru/calcit-core.cirru").unwrap_or_else(|e| panic!("failed to read src/cirru/calcit-core.cirru: {e}"));
+  let core_data = cirru_edn::parse(&core_content)
+    .unwrap_or_else(|e| panic!("failed to parse src/cirru/calcit-core.cirru as Cirru EDN: {}", format_edn_error(e)));
 
   // Minimal logic to convert Edn to Snapshot as in src/snapshot.rs
-  let data = core_data.view_map().expect("map");
-  let pkg: String = from_edn(data.get_or_nil("package")).expect("pkg");
+  let data = core_data
+    .view_map()
+    .unwrap_or_else(|e| panic!("calcit-core snapshot root must be a map: {e}"));
+  let pkg: String = from_edn(data.get_or_nil("package")).unwrap_or_else(|e| panic!("failed to parse calcit-core `:package`: {e}"));
   let about = match data.get_or_nil("about") {
     Edn::Nil => None,
-    value => Some(from_edn::<String>(value).expect("about")),
+    value => Some(from_edn::<String>(value).unwrap_or_else(|e| panic!("failed to parse calcit-core `:about`: {e}"))),
   };
 
-  let files: HashMap<String, FileInSnapShot> = from_edn(data.get_or_nil("files")).expect("files");
+  let files = parse_files(data.get_or_nil("files")).unwrap_or_else(|e| panic!("failed to parse calcit-core `:files`: {e}"));
 
   let snapshot = Snapshot {
     package: pkg,
     about,
-    configs: from_edn(data.get_or_nil("configs")).expect("configs"),
-    entries: from_edn(data.get_or_nil("entries")).expect("entries"),
+    configs: from_edn(data.get_or_nil("configs")).unwrap_or_else(|e| panic!("failed to parse calcit-core `:configs`: {e}")),
+    entries: from_edn(data.get_or_nil("entries")).unwrap_or_else(|e| panic!("failed to parse calcit-core `:entries`: {e}")),
     files,
   };
 
   let mut buf = Vec::new();
-  snapshot.serialize(&mut rmp_serde::Serializer::new(&mut buf)).expect("serialize");
-  fs::write(dest_path, buf).expect("write");
+  snapshot
+    .serialize(&mut rmp_serde::Serializer::new(&mut buf))
+    .unwrap_or_else(|e| panic!("failed to serialize embedded calcit-core snapshot: {e}"));
+  fs::write(dest_path, buf).unwrap_or_else(|e| panic!("failed to write embedded calcit-core snapshot: {e}"));
 }

package/editing-history/2026-0305-0042-type-inference-argtypes-and-core-hints.md

@@ -0,0 +1,54 @@
+# 2026-03-05 类型推断增强记录
+
+## 本次目标
+
+- 在 upstream 重置后，重新加强类型推断能力，并保证 debug/release/全量检查都稳定通过。
+
+## 关键改动
+
+### 1) 预处理阶段 Proc 返回类型传播增强
+
+在 `src/runner/preprocess.rs` 的 `infer_type_from_expr` 中补齐多类内建过程返回类型推断：
+
+- List 保型：`sort`、`&list:concat`、`&list:assoc`、`&list:assoc-before`、`&list:assoc-after`、`&list:dissoc`。
+- 固定返回：`range -> list<number>`，`split/split-lines -> list<string>`，`&map:to-list -> list`。
+- Map 保型：`&map:assoc`、`&map:dissoc`、`&merge`、`&merge-non-nil`、`&map:diff-new`。
+- Set 保型：`&include`、`&exclude`、`&difference`、`&union`、`&set:intersection`。
+
+### 2) defn 参数类型提示传播修复（避免栈溢出）
+
+在 `src/builtins/syntax.rs` 中增强 `defn` 的 `arg_types` 回退策略：
+
+- 第一层：沿用原逻辑，从 body 中 `assert-type` 模式提取。
+- 第二层：当全是 Dynamic 时，从参数列表 Local 的 `type_info` 读取。
+- 第三层：当仍全是 Dynamic 时，从**预处理后 body 顶层 Local**提取（`assert-type` 被预处理成 typed local 的场景）。
+- 为避免核心加载路径栈压力，`calcit.core` 命名空间跳过该额外回退扫描。
+
+### 3) calcit-core 类型提示细化
+
+在 `src/cirru/calcit-core.cirru` 为以下列表保型函数补充泛型提示：
+
+- `distinct`
+- `drop`
+- `repeat`
+- `reverse`
+- `take`
+- `take-last`
+
+统一使用 `hint-fn (generics 'T) $ return-type (:: :list 'T)`，并将输入列表参数改为 `assert-type ... (:: :list 'T)`。
+
+### 4) 测试用例一致性调整
+
+`calcit/test-types.cirru` 中 `test-arg-type-hints` 示例从故意错误参数改为合法参数，避免新检查路径把 warning 升级为阻断导致全量检查失败。
+
+## 过程中的关键排障结论
+
+- 多次尝试在 `preprocess_defn` 内直接重建/替换参数 AST 或引入额外全局缓存时，容易触发主流程栈溢出。
+- 最终采用“最小干预 + 避开 core 热路径回退扫描”的方式稳定通过。
+
+## 验证结果
+
+- `cargo test` 通过。
+- `yarn check-all` 通过（`EXIT:0`）。
+- `cargo build --release` + `./target/release/cr calcit/test.cirru -1` 通过。
+- `./target/debug/cr calcit/test.cirru -1` 通过。

package/editing-history/2026-0305-0115-calcit-core-generic-refinements.md

@@ -0,0 +1,57 @@
+# 2026-03-05 calict.core 泛型签名细化
+
+## 目标
+
+在不改变运行时语义的前提下，继续收紧 `calcit-core.cirru` 中 `defn` 的类型签名，让类型推断更稳定、错误提示更精确。
+
+## 主要改动
+
+本次聚焦于“保型列表函数”“可选返回值函数”“函数组合器”“map 回调函数形状”四类。
+
+### 一、列表保型与可选返回
+
+- `distinct`, `drop`, `repeat`, `reverse`, `take`, `take-last`
+  - 统一到 `hint-fn (generics 'T) $ return-type (:: :list 'T)`。
+- `&list:find-last`
+  - 改为 `(:: :optional 'T)`。
+- `&list:find-last-index`, `&list:last-index-of`, `index-of`
+  - 改为 `(:: :optional :number)`。
+- `&list:max`, `&list:min`
+  - 改为 `(:: :optional 'T)`。
+
+### 二、列表/映射映射函数泛型化
+
+- `&list:map`
+  - 从宽泛 `:list/:fn` 收紧到 `('T -> 'U)`，返回 `(:: :list 'U)`。
+- `map`
+  - 回调从 `('T -> 'T)` 扩展为 `('T -> 'U)`，与 map 语义一致。
+- `map-indexed`
+  - 返回类型显式为 `(:: :list 'U)`，回调签名改为 `(:number 'T) -> 'U`。
+
+### 三、拼接与组合函数
+
+- `concat`, `conj`, `interleave`, `join`
+  - 输入与输出统一到同一元素类型 `'T` 的列表。
+- `&list:apply`
+  - 收紧为 `xs: list<T>, fs: list<(T -> U)>`，返回 `list<U>`。
+
+### 四、函数组合器与 map helper
+
+- `&fn:apply`, `&fn:bind`, `&fn:map`
+  - 增加 `('A 'B 'C)` 级别泛型，表达组合器的真实输入输出关系。
+- `&map:map-list`
+  - 返回改为 `(:: :list 'U)`，并补充 `f/acc/pair` 类型约束。
+- `&list:map-pair`
+  - 返回改为 `(:: :list 'U)`，`f` 改为 `('K 'V) -> 'U`。
+- `&map:filter`, `&map:filter-kv`, `&map:map`
+  - 回调签名改为带输入/输出形状的泛型函数类型，减少 `:fn` 过宽带来的误判。
+
+## 验证
+
+日志均写入仓库内 `js-out/`：
+
+- `yarn check-all > js-out/check-all.log`，`EXIT:0`
+- `cargo build --release > js-out/release-build.log`
+- `./target/release/cr calcit/test.cirru -1 > js-out/release-run.log`，`EXIT:0`
+
+结论：本次改动仅增强静态类型信息，未改变运行行为，且全量检查通过。

package/editing-history/2026-0305-1930-schema-migration-cr-edit.md

@@ -0,0 +1,30 @@
+# 2026-03-05 19:30 schema 迁移记录
+
+## 本次改动
+
+- 持续使用 `cr edit schema` 迁移 `src/cirru/calcit-core.cirru` 中 `defn` 的 `:schema`。
+- 统一命令形式为：
+  - entry 使用 `src/cirru/calcit-core.cirru`
+  - target 使用 `namespace/definition`
+  - schema 使用 pair map 语法：`{} (:kind :fn) (:args ...) (:return ...)`
+- 对包含 `?` 的函数名（如 `set?`）在 shell 中使用引号，避免 zsh 通配展开。
+
+## 迁移经验
+
+- `cr -- calcit/test.cirru edit schema calcit.core/...` 会触发“只允许 app 包编辑”，改用 core 源文件作为 entry 可编辑 core namespace。
+- schema map 在 `-e` 中不能写成 `:args ... :return ...` 平铺键值，必须写成 `(:args ...)`、`(:return ...)` 的 pair。
+- 批量链式命令中若某个目标失败，会中断后续目标；迁移后需要用搜索确认实际落盘范围。
+
+## 本轮补充的 schema（代表性）
+
+- `section-by`, `select-keys`, `set?`, `slice`, `some-in?`, `some?`
+- `str`, `str-spaced`, `string?`, `strip-prefix`, `strip-suffix`
+- `struct?`, `symbol?`, `syntax?`, `tag?`, `tagging-edn`
+- `take`, `take-last`, `thread-step?`, `tuple?`, `turn-str`
+- `union`, `unselect-keys`, `update`, `update-in`
+- `option:map`, `optionally`, `pairs-map`, `range-bothway`, `result:map`, `vals`, `zipmap`
+- `calcit.internal/normalize-trait-type`
+
+## 验证
+
+- 运行通过：`cargo test && yarn check-all`。

package/editing-history/2026-0305-1939-query-schema-adaptation.md

@@ -0,0 +1,42 @@
+# 2026-03-05 19:39 query schema 适配
+
+## 改动概要
+
+- 针对 `cr query` 工具链补充 schema 感知与展示，修改文件：
+  - `src/bin/cli_handlers/query.rs`
+
+## 具体更新
+
+- `query defs <ns>`
+  - 对带 schema 的定义添加 `[schema]` 提示，便于快速识别迁移覆盖率。
+
+- `query def <ns/def>`
+  - 新增 `Schema` 区块输出（无 schema 时显示 `(none)`）。
+  - `--json` 输出从仅 code 扩展为完整 `CodeEntry` 结构：
+    - `doc`
+    - `examples`
+    - `code`
+    - `schema`
+
+- `query peek <ns/def>`
+  - 新增 schema 预览（one-liner，超长截断）。
+
+- `query find <symbol>`
+  - 引用搜索范围从 `code` 扩展到 `schema`。
+  - 输出中标注命中来源 `[code]` / `[schema]`。
+
+- `query usages <ns/def>`
+  - 用法搜索范围从 `code` 扩展到 `schema`。
+  - 输出中标注命中来源 `[code]` / `[schema]`。
+
+## 兼容性说明
+
+- 未新增 CLI 参数，保持原命令兼容；schema 能力默认生效。
+- 仅增强查询展示与搜索语义，不影响运行时求值逻辑。
+
+## 验证
+
+- 已执行并通过：
+  - `cargo fmt`
+  - `cargo test`
+  - `yarn check-all`

package/editing-history/2026-0306-0120-schema-hint-migration-batch.md

@@ -0,0 +1,38 @@
+# 2026-03-06 01:20 Schema Hint Migration Batch
+
+## 概要
+
+本次集中推进 `hint-fn` 新 schema map 语法迁移，覆盖 core 与测试快照中的多批函数/示例；并持续以 `cargo run --bin cr -- calcit/test.cirru -1` 与 `yarn check-all` 做回归验证。
+
+## 关键变更点
+
+- 在 `src/cirru/calcit-core.cirru` 中将大量旧写法 `hint-fn $ return-type ...` 迁移为：
+  - `hint-fn $ {}`
+  - `:args` / `:rest` / `:return` / `:generics` 等字段显式表达
+- 对已由 `:args`/`:rest` 覆盖的参数类型，移除冗余 `assert-type`（保持必要运行时校验逻辑不变）。
+- 同步修正若干 schema 与实现不一致处（例如部分参数应为 `:number`/`:fn` 的场景）。
+- 完成多处嵌套局部函数（如 `%map`、`%map-indexed`、`%pairs-map`、`%select-keys`、`%repeat` 等）的 hint 迁移。
+- 继续保持 `calcit/*.cirru` 测试快照侧的新语法一致性。
+
+## 工具与流程
+
+- 使用新增命令 `cr edit format` 对变更的 snapshot 文件做规范化重写：
+  - `src/cirru/calcit-core.cirru`
+  - `calcit/test-generics.cirru`
+  - `calcit/test-js.cirru`
+  - `calcit/test-types-inference.cirru`
+  - `calcit/test-types.cirru`
+- 使用 `cargo fmt` 统一 Rust 代码格式。
+
+## 验证
+
+- 多轮执行并通过：
+  - `cargo run --bin cr -- calcit/test.cirru -1`
+  - `yarn check-all`
+- 迁移过程中持续统计 `src/cirru/calcit-core.cirru` 内剩余旧模式数量，确认总体下降趋势。
+
+## 经验
+
+- 在 schema-first 迁移中，优先迁移“签名简单、类型清晰”的函数可快速稳定推进。
+- 对复杂逻辑函数保留运行时断言，但避免与 `:args` 重复声明同一层参数类型。
+- 每批次后立即执行 targeted + full 验证，能快速定位回归并降低累计风险。

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` 通过。

package/editing-history/2026-0308-2033-schema-wrapper-migration.md

@@ -0,0 +1,45 @@
+# 2026-03-08 schema wrapper migration
+
+## Summary
+
+- 统一函数 schema 的 snapshot 输出格式，顶层改为 wrapped `:: :fn` / `:: :macro` 形式。
+- 修复 schema round-trip 中的类型信息丢失，确保嵌套函数类型与 `:rest` 在格式化后保持稳定。
+- 将 macro schema 的顶层格式统一迁移到 `:: :macro`，并让 formatter 在处理 `defmacro` 条目时自动纠正旧的 `fn` 标记。
+- 移除 legacy quote-wrapped schema normalization 与 legacy positional `fn` type annotation fallback，收紧到当前 schema-map 形式。
+- 更新 `deftrait` 文档与相关说明，避免继续传播旧写法。
+
+## Main changes
+
+### 1) 顶层 schema 输出统一
+
+- 在 `src/calcit/type_annotation.rs` 中补充顶层 wrapped schema 的解析与序列化逻辑。
+- 在 `src/snapshot.rs` 中让 `CodeEntry.schema` 写回 snapshot 时统一输出为 `:schema $ :: :fn ...` 或 `:schema $ :: :macro ...`。
+- 对 plain fn schema 去掉 wrapped payload 内冗余的 `:kind :fn`，但保留宏函数所需的 `:kind :macro`。
+
+### 2) macro schema 迁移与规范化
+
+- 扩展 parser / normalize 逻辑，使其同时接受 wrapped `fn` 与 wrapped `macro`。
+- 对 macro schema，序列化时省略冗余的 `:kind :macro` 与 `:return`，仅保留 `:args` 与可选 `:rest`。
+- 在 snapshot 读写路径中，根据代码头是否为 `defmacro` 自动纠正 schema kind。
+
+### 3) legacy fn syntax 收紧
+
+- 移除 legacy quote-wrapped schema normalization。
+- 拒绝 legacy quoted generic symbols。
+- 移除 legacy positional `fn` type annotation parsing fallback。
+- 迁移剩余 core trait 与测试注解到 schema-map `:: :fn {}` 形式。
+
+### 4) round-trip 与批量格式化
+
+- 修复 EDN 到 Calcit 的转换路径，补上 `Edn::Map` 的处理，避免嵌套 `fn` schema 的 hashmap payload 被吞掉后退化成 `:dynamic`。
+- 调整 schema 校验与 normalize 逻辑，使 wrapped 顶层 fn schema 与旧格式都能稳定读写。
+- 重新格式化了 `src/cirru/calcit-core.cirru`、`calcit/util.cirru`、`calcit/test-hygienic.cirru` 等兼容 snapshot 文件。
+
+## Validation
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `yarn compile`
+- `cargo test -q`
+- `cargo build -q`
+- `yarn check-all`

package/editing-history/2026-0308-2315-late-schema-cleanup-and-warning-compat.md

@@ -0,0 +1,27 @@
+# 2026-03-08 late schema cleanup and warning compatibility
+
+## Summary
+
+- made snapshot schema loading strict for non-nil schemas, so malformed schema data no longer silently degrades to dynamic
+- normalized loaded schema maps so legacy string keys and string `:kind` values are converted into canonical tag-based schema maps
+- restored generic type variables in `src/cirru/calcit-core.cirru` where a previous migration had incorrectly replaced them with `:symbol`
+- cleaned the remaining mistaken `:symbol` placeholders in core collection schemas, keeping only the intentional `symbol?` runtime type check
+- fixed `calcit/test-generics.cirru` after a schema-formatting edit moved `assert-type id ...` into the `let` binding section
+- kept `ns/def` warning location reporting for embedded core snapshot loading
+- stopped legacy fn-schema warnings from firing on malformed nested `:: :fn` schema payloads parsed from `calcit-core.cirru`
+- used a conservative fallback to `DynFn` for malformed nested payloads, avoiding false-positive callback type warnings without re-editing Cirru syntax
+
+## Notes
+
+- `yarn check-all` passed after the generic-schema restoration and remaining `:symbol` cleanup passes
+- the `test-generics` fix resolves the runtime error `expected binding of a pair`
+- nested function schema payloads coming from Cirru snapshot EDN may currently collapse into malformed map payloads like `(:: :fn ({} (nil ...)))` or `(:: :fn ({}))`
+- those malformed payloads are lossy, so partially reconstructing arg/return types can introduce new static-analysis warnings
+- decoding the embedded binary core snapshot with per-entry owners is necessary to preserve precise warning locations such as `calcit.core/foo`
+
+## Validation
+
+- `cargo test -q malformed_nested_fn_schema`
+- `cargo build -q`
+- `target/debug/cr calcit/test.cirru -1`
+- `yarn check-all`

package/lib/package.json

@@ -1,13 +1,13 @@
 {
     "name": "@calcit/procs",
-    "version": "0.11.8",
+    "version": "0.12.0",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",
         "typescript": "^5.9.3"
     },
     "scripts": {
-        "compile": "rm -rfv lib/* && tsc",
+        "compile": "rm -rf lib && tsc",
         "procs-link": "ln -sfn ../../ node_modules/@calcit/procs",
         "cp-mac": "cargo build --release && rm -rfv builds/* && node scripts/cp-version.js && scp builds/* rsync-user@calcit-lang.org:/web-assets/repo/calcit-lang/binaries/macos/",
         "eval": "cargo run --bin cr -- eval",

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@calcit/procs",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",
     "typescript": "^5.9.3"
   },
   "scripts": {
-    "compile": "rm -rfv lib/* && tsc",
+    "compile": "rm -rf lib && tsc",
     "procs-link": "ln -sfn ../../ node_modules/@calcit/procs",
     "cp-mac": "cargo build --release && rm -rfv builds/* && node scripts/cp-version.js && scp builds/* rsync-user@calcit-lang.org:/web-assets/repo/calcit-lang/binaries/macos/",
     "eval": "cargo run --bin cr -- eval",