@calcit/procs 0.12.35 → 0.12.37

package/README.md

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

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

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

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

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