@calcit/procs 0.11.7 → 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-0303-1934-check-types-and-core-annotations.md

@@ -0,0 +1,17 @@
+## 本次修改摘要
+
+- 新增 `cr analyze check-types` 子命令，用于统计定义的类型标注覆盖度。
+- 支持按命名空间过滤：`--ns`、`--ns-prefix`，以及是否包含依赖：`--deps`。
+- 支持覆盖度分层与筛选：`none/partial/full`，并通过 `--only` 过滤输出。
+- 优化输出格式：按定义类型（fn/macro/data）分块展示，参数与断言信息合并展示，`return-type` 标签统一为 `return`。
+- 持续补充 `calcit.core` 中函数参数 `assert-type` 标注，`partial` 覆盖项降至 0（`--only partial` 无结果）。
+
+## 验证
+
+- 执行 `yarn check-all`：通过。
+- 执行 `./target/debug/cr calcit/test.cirru analyze check-types --ns calcit.core --deps --only partial`：无 `partial` 定义。
+
+## 经验记录
+
+- 日常编辑可优先使用全局 `cr tree/edit`，减少 `cargo run` 反复编译开销。
+- 若全局 `cr` 尚未包含新子命令（如 `analyze check-types`），统计/验证阶段需使用仓库内最新二进制（如 `./target/debug/cr`）。

package/editing-history/2026-0304-1331-tag-call-warning-and-dot-access-migration.md

@@ -0,0 +1,28 @@
+# trait/impl 方法键 tag 写法 warning 与点号迁移评估
+
+## 背景
+
+- `deftrait` / `defimpl` 里方法键目前使用 `:foo` 形式，语义上对应方法名。
+- 为逐步迁移到点号方法表示（如 `.foo`）需要先在 trait/impl 场景给出提示，避免误伤普通 tag/map 使用。
+
+## 本次改动
+
+- 在 `src/runner/preprocess.rs` 的宏预处理分支新增 warning：
+  - 仅在 `deftrait` / `defimpl` 检查方法键（默认展示）。
+  - 检测到 `:foo` 方法键时提示迁移到 `.foo` 风格（兼容性保留）。
+- 移除对普通 `(:k obj)` 访问调用的迁移 warning，避免范围跑偏。
+- 新增单测 `warns_on_trait_impl_method_tag_syntax`，确保 warning 范围和文案稳定。
+- 同步在 `calcit/*.cirru` 的 trait/impl 测试与示例中开始迁移到 `.foo` 写法。
+
+## 迁移建议（分阶段）
+
+1. **当前阶段（已落地）**：默认 warning + 兼容旧写法。
+2. **下一阶段**：在文档与脚手架模板中默认采用 `.foo` 方法键表示。
+3. **后续阶段（可选）**：提供自动改写工具（`deftrait/defimpl` 的 `:foo` -> `.foo`）并支持批量修复。
+4. **最终阶段（可选）**：再评估是否提升 warning 严格度（例如 lint 级别开关）。
+
+## 验证
+
+- 定向测试：
+  - `cargo test warns_on_trait_impl_method_tag_syntax -- --nocapture`
+  - `cargo test warns_on_dynamic_trait_call -- --nocapture`

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

@@ -0,0 +1,33 @@
+# 2026-03-04 15:48 `&impl::new` dot-method 输入与文档提示对齐
+
+## 背景
+
+在 trait/impl method key 迁移到 `.method` 的过程中，声明层（`deftrait`/`defimpl`）已支持并迁移，但原生构造入口 `&impl::new` 在不同后端对 `.method` 输入支持不一致：Rust 侧与 JS 侧行为存在差异，导致 `yarn check-all` 的 JS 路径报错。
+
+## 本次改动要点
+
+- 扩展 `&impl::new` 字段键解析，支持 `.method` 输入并规范化为内部 tag 键：
+  - Rust: `src/builtins/records.rs` 接受 `Calcit::Method` 作为 field key。
+  - JS: `ts-src/calcit.procs.mts` 为 method closure 写入 `__calcitMethodName` 元信息；`ts-src/calcit-data.mts` 的 `castTag` 可读取该元信息并转为 tag。
+- 增加回归用例：
+  - `calcit/test-doc-smoke.cirru` 新增 `test-native-impl-new-dot-method`，直接覆盖 `&impl::new` + `.method` 场景。
+- 补齐文档与示例提示（用于 `query examples` 与错误 hint 链路）：
+  - `src/cirru/calcit-core.cirru` 新增 `calcit.core/&impl::new` 的 `CodeEntry` 和 `.method` 示例。
+  - 更新 `&impl:get` 参数说明支持 `.method`，并新增 `&impl:get DemoImpl .show` 示例。
+
+## 迁移语义结论
+
+- 声明层：推荐 `.method`，legacy `:method` 兼容（并有 warning 提示）。
+- 存储层：继续保持 tag 作为内部键（兼容和最小改动优先）；本次仅扩展输入层与提示层，不改内部数据结构。
+
+## 验证
+
+- `cargo fmt --check`
+- `cargo clippy -- -D warnings`
+- `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'`
+
+以上在本次改动后均通过。

package/editing-history/2026-0304-1645-calcit-eq-contract-refactor-and-macro-tests.md

@@ -0,0 +1,28 @@
+# 2026-03-04 16:45 `Calcit` 等值契约收敛、比较逻辑拆分与宏测试期望对齐
+
+## 背景
+
+在将 `Calcit` 的 `Eq/Hash/Ord` 契约对齐后，`Symbol/Local/Import` 的跨变种相等被移除，暴露了若干 `macroexpand-all` 测试中“符号 vs 已解析 core import”比较不一致的问题。
+
+## 本次改动
+
+- 运行时契约修复（`src/calcit.rs`）：
+  - 移除 `Symbol/Local/Import` 跨变种相等特判。
+  - 补齐 `Trait/Impl/Struct` 相关 hash 字段，避免 `Eq` 与 `Hash` 不一致。
+  - `Struct/Enum/Trait/Impl` 的 `Ord` 比较从仅按 name 改为与 `Eq` 语义一致。
+- 比较辅助函数拆分（`src/calcit/compare.rs`）：
+  - 将 `compare_*` 辅助逻辑独立成模块，减轻 `calcit.rs` 体积与复杂度。
+- 宏测试期望修复（`calcit/test-macro.cirru`）：
+  - 将多处 `quasiquote` 直接期望改为“左右均 `macroexpand-all` 再比较”，避免因 `calcit.core/+`、`calcit.core/=` 的 `Import`/`Symbol` 差异导致伪失败。
+
+## 经验与约束
+
+- 当核心值语义从“宽松相等”收敛为“严格相等”后，宏展开测试应优先比较**同一归一化阶段**产物，而不是混比 `quasiquote` 与 `macroexpand-all` 原始结果。
+- 若测试目标是“展开形状正确”，可比较两侧都经过 `macroexpand-all` 的 AST，降低名称解析层差异带来的噪声。
+
+## 验证
+
+- `cargo test`
+- `yarn check-all`
+
+均通过。

package/editing-history/2026-0304-2200-assert-type-assert-traits-composable-runtime-checks.md

@@ -0,0 +1,18 @@
+# assert-type/assert-traits 可组合语义与检查路径修复
+
+## 背景
+- `assert-type`/`assert-traits` 之前在 runtime 路径不完整，且 `assert-type` 不可组合。
+- 在补 runtime 之后出现过 `yarn check-all` 栈溢出，需要在可组合性与稳定性间做执行路径分流。
+
+## 关键调整
+- `assert-type` 通过时返回原值，失败时报错，可嵌套表达式。
+- `assert-traits` 接入 syntax runtime，支持多个 trait 断言并返回原值。
+- preprocess 分流：
+  - local 目标：保留静态类型注入/细化（避免破坏加载路径）；
+  - expression 目标：保留到 runtime 断言，保证组合性。
+- 补齐 `if` 返回类型推断与方法参数泛型绑定匹配。
+
+## 验证
+- 新增/更新单测通过（runtime + preprocess 路径）。
+- `cargo test` 通过。
+- `yarn check-all` 通过（EXIT 0）。

package/editing-history/2026-0304-generics-fn-typevar-identity.md

@@ -0,0 +1,30 @@
+# 泛型函数 TypeVar 返回类型推导 (identity 用例)
+
+## 概要
+
+实现 `hint-fn (generics 'T)` 语法用于函数泛型声明，使 `identity` 等泛型函数的返回类型能在调用处根据实参类型自动推导。
+
+## 核心改动
+
+### `src/calcit/type_annotation.rs`
+
+- 新增 `substitute_type_vars(&self, bindings) -> Arc<CalcitTypeAnnotation>`：将注解中的 `TypeVar` 替换为 `bindings` 中已绑定的具体类型，未绑定的保留原样。递归处理 `List`、`Map`、`Set`、`Ref`、`Optional`、`Variadic`、`Fn`、`AppliedStruct` 等复合类型。
+- 新增 `contains_type_var(&self) -> bool`：判断注解中是否包含 `TypeVar`，用于快速跳过不需要泛型解析的路径。
+- `extract_generics_from_hint_form` 中增加对 `"generics"` 关键字的识别（原来只识别 `"type-vars"`）。
+
+### `src/runner/preprocess.rs`
+
+- 新增 `resolve_generic_return_type(fn_info, call_args, scope_types)`：当被调函数的返回类型包含 TypeVar 时，用 `matches_with_bindings` 将实参类型与形参注解匹配以收集绑定，然后用 `substitute_type_vars` 替换返回类型中的 TypeVar。
+- `infer_type_from_expr` 中 4 个返回 `info.return_type.clone()` 的路径（Import evaled、Import code、Symbol lookup、直接 Fn head）在检测到 TypeVar 返回类型时，优先尝试 `resolve_generic_return_type`。
+- `check_function_return_type` 中，当声明的返回类型包含 TypeVar 时跳过定义体校验（泛型返回类型只在调用处才可确定）。
+
+### `calcit/test-types-inference.cirru`
+
+- 新增 `test-generics-identity` 测试：验证 `identity 42` 推导为 `:number`、`identity |hello` 推导为 `:string`。
+
+## 验证
+
+- `cargo test` 全部通过
+- `cargo clippy -- -D warnings` 无警告
+- `yarn check-all` 全量集成测试通过
+- `&inspect-type` 输出确认 `'n => number`、`'s => string`

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 验证，能快速定位回归并降低累计风险。