@calcit/procs 0.11.8 → 0.12.1

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-0000-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。