@calcit/procs 0.12.51 → 0.12.53

package/RFCs/README.md

@@ -1,6 +1,6 @@
 # RFC 整理索引
 
-更新时间：2026-06-29
+更新时间：2026-07-26
 
 ## 目录原则
 
@@ -32,6 +32,7 @@
 | `07-06-semantic-tree-navigation-rfc.md`             | Draft         | 语义化树形导航与编辑：路径标注、多候选交互、锚点搜索替换、结构化查询语言。                |
 | `07-19-doc-knowledge-index-rfc.md`                  | Draft         | Markdown/Calcit snapshot 的知识节点、关系索引与用户级增量缓存方案。                       |
 | `07-19-type-introspection-consistency-rfc.md`       | Implemented   | 类型自省一致性改进：`&methods-of` 支持裸类型定义、`Enum` Display 补 variants、`to-pairs`/`keys` 类型签名修正（第 4 项可选新增 proc 延后）。 |
+| `07-26-agent-semantic-interface-roadmap-rfc.md`     | Draft         | 面向 LLM Agent 的统一语义查询、静态类型发现、文档索引、结构化诊断、事务编辑和效率基准路线图。                            |
 
 ## 已执行的清理
 

package/editing-history/2026-02-23-2321-ns-imports-code-fixes.md

@@ -6,9 +6,9 @@
 
 ## 发现的 Bug
 
-### Bug 1：`imports -e 'rule'` 产生平坦结构，与 `extract_require_rules` 不兼容
+### Bug 1：`imports --code 'rule'` 产生平坦结构，与 `extract_require_rules` 不兼容
 
-- **现象**：`imports -e 'respo.core :refer $ sym'` 成功，但之后执行 `add-import` 会丢失已有 imports
+- **现象**：`imports --code 'respo.core :refer $ sym'` 成功，但之后执行 `add-import` 会丢失已有 imports
 - **根因**：`handle_imports` 手工拼接 `ns_code_items`（平坦 list），产生结构：
   ```
   ["ns", "my.ns", ":require", "respo.core", ":refer", "$", "sym"]
@@ -20,14 +20,14 @@
   导致后续任何依赖 `extract_require_rules` 的操作（`add-import`、`rm-import`）全部解析不到已有规则。
 - **修复**：重写 `handle_imports` 的 rules 解析逻辑，统一调用 `build_ns_code` 生成嵌套结构。同时自动区分输入是单条规则（flat array of strings）还是多条规则（array of arrays）。
 
-### Bug 2：`imports -e ':require ...'` 静默产生 `:require :require` 重复
+### Bug 2：`imports --code ':require ...'` 静默产生 `:require :require` 重复
 
 - **现象**：写 `:require respo.core :refer $ sym` 不报错，但生成 `ns my.ns :require :require respo.core ...`
 - **修复**：当 Cirru 解析后发现数组第一元素为 `:require` 字符串，立即返回错误消息，引导用户不包含 `:require` 前缀。
 
-### Bug 3：`add-ns -e 'ns WRONG_NAME ...'` 名称不一致静默通过
+### Bug 3：`add-ns --code 'ns WRONG_NAME ...'` 名称不一致静默通过
 
-- **现象**：`cr edit add-ns my.ns -e 'ns wrong.ns ...'` 成功，file-key 是 `my.ns`，但 ns 声明内写的是 `wrong.ns`，导致 `query ns my.ns` 看到内部名称错误
+- **现象**：`cr edit add-ns my.ns --code 'ns wrong.ns ...'` 成功，file-key 是 `my.ns`，但 ns 声明内写的是 `wrong.ns`，导致 `query ns my.ns` 看到内部名称错误
 - **修复**：当输入解析为 `ns` 表达式时，校验第二个元素是否与位置参数一致，不一致则 Error。
 
 ## 修改文件
@@ -36,7 +36,7 @@
 
 ## 知识点
 
-- `imports` 命令的 `-e` 输入格式：**不含 `:require` 前缀**，直接是规则体（`src-ns :refer $ sym`）。单条规则传平坦字符串，多条规则用 `-f` 文件（每行一条）或 `-j` JSON 数组（元素为数组）。
+- `imports` 命令的 `--code` 输入格式：**不含 `:require` 前缀**，直接是规则体（`src-ns :refer $ sym`）。单条规则用 `--code`，多条规则用 `--file`（每行一条）或通过 stdin 传 JSON 数组（元素为数组）。
 - `add-import` 和 `imports` 的格式一致，都是 `src-ns :refer $ sym`（无 `:require` 前缀）。
-- `add-ns -e` 中若传完整 `ns` 表达式，内部名称必须与位置参数完全匹配。
+- `add-ns --code` 中若传完整 `ns` 表达式，内部名称必须与位置参数完全匹配。
 - 最佳实践：优先使用 `add-import`（带保护和覆盖控制），`imports` 只在需要全量重置时使用。

package/editing-history/2026-02-27-2200-split-def-command.md

@@ -2,11 +2,11 @@
 
 ## 改动概要
 
-新增 `cr edit split-def <ns/def> -p <path> -n <new-name>` 命令，用于将某定义内指定路径的子表达式提取为同命名空间内的一个新定义，原位置替换为新定义的名字。
+新增 `cr edit split-def <ns/def> --path <path> --name <new-name>` 命令，用于将某定义内指定路径的子表达式提取为同命名空间内的一个新定义，原位置替换为新定义的名字。
 
 ## 修改文件
 
-- `src/cli_args.rs`：新增 `EditSplitDefCommand` struct（参数：`target`, `-p/--path`, `-n/--name`）；在 `EditSubcommand` 枚举中新增 `SplitDef(EditSplitDefCommand)` 变体。
+- `src/cli_args.rs`：新增 `EditSplitDefCommand` struct（参数：`target`, `--path`, `--name`）；在 `EditSubcommand` 枚举中新增 `SplitDef(EditSplitDefCommand)` 变体。
 - `src/bin/cli_handlers/edit.rs`：import 增加 `EditSplitDefCommand`；dispatch 增加 `EditSubcommand::SplitDef`；实现 `handle_split_def` 函数。
 - `docs/CalcitAgent.md`：
   1. 修复 `tree unwrap` 示例（移除已废弃的 `-i 1` 参数，更新描述为 splice 所有子节点语义）。
@@ -26,4 +26,4 @@
 
 - `split-def` 只操作 AST，不会自动添加 import。如果新定义需要被其他 ns 引用，需手动 `cr edit add-import`。
 - 路径索引规则与 `cr tree` 系列一致（逗号分隔，0-based）。
-- 提取后如需给新定义包装成 `defn` 函数形式，用 `cr tree replace <ns/new-name> -p '' -e 'defn new-name (args...) ...'`。
+- 提取后如需给新定义包装成 `defn` 函数形式，用 `cr tree replace <ns/new-name> --path '' --code 'quote (defn new-name (args...) ...)'`。

package/editing-history/2026-02-27-2212-tree-raise-wrap.md

@@ -12,7 +12,7 @@
 
 ## 命令语义
 
-### `cr tree raise <ns/def> -p <child-path>`
+### `cr tree raise <ns/def> --path <child-path>`
 
 等价 Paredit `raise-sexp`。将指定子节点**整体替换掉其父节点**。
 
@@ -20,11 +20,11 @@
 - `parent_path = path[..n-1]`，用 `apply_operation_at_path(..., "replace", child)` 实现
 - 典型用途：去掉 `if` 只保留某分支、去掉 `let` 只保留最终返回值表达式
 
-### `cr tree wrap <ns/def> -p <path> -e '<template>'`
+### `cr tree wrap <ns/def> --path <path> --code '<template>'`
 
-等价 `cr tree rewrite ... -w 'self=.'`，但更简洁。模板中 `self` 自动绑定为原节点。
+等价 `cr tree rewrite ... --with 'self=.'`，但更简洁。模板中 `self` 自动绑定为原节点。
 
-- 适合"加一层调用"的常见模式：`wrap -e 'println self'`、`wrap -e 'let ((x self)) x'`
+- 适合"加一层调用"的常见模式：`wrap --code 'println self'`、`wrap --code 'let ((x self)) x'`
 - 当需要引用原节点的**子节点**（不只是整体）时，仍需用 `rewrite --with`
 
 ## 知识点

package/editing-history/2026-03-10-1040-edit-schema-primitive-tag-support.md

@@ -8,9 +8,9 @@
 ## 新语法
 
 ```bash
-cr edit schema 'respo.comp.space/style-space' --leaf -e ':string'
-cr edit schema 'some.ns/my-val' --leaf -e ':number'
-cr edit schema 'some.ns/my-flag' --leaf -e ':bool'
+cr edit schema 'respo.comp.space/style-space' --code 'quote :string'
+cr edit schema 'some.ns/my-val' --code 'quote :number'
+cr edit schema 'some.ns/my-flag' --code 'quote :bool'
 ```
 
 接受的 primitive 类型 tag：`bool`, `number`, `string`, `symbol`, `tag`, `list`, `map`, `set`, `fn`, `tuple`, `ref`, `buffer`, `dynamic`, `unit`
@@ -35,7 +35,7 @@ cr edit schema 'some.ns/my-flag' --leaf -e ':bool'
 
 ## 完整数据流（以 `:string` 为例）
 
-1. CLI 收到 `--leaf -e ':string'` → `Cirru::Leaf(":string")`
+1. CLI 收到 quoted schema 输入 `--code 'quote :string'`，取出 payload 后得到 `Cirru::Leaf(":string")`
 2. `validate_schema_for_write` → `"string"` 在 `PRIMITIVE_SCHEMA_TAGS` → Ok
 3. `CalcitTypeAnnotation::from_tag_name("string")` → `CalcitTypeAnnotation::String`
 4. 写入快照 → `CodeEntry::From` 序列化为 `Edn::tag("string")`

package/editing-history/2026-07-26-1220-to-js-data-options.md

@@ -0,0 +1,14 @@
+# 2026-07-26 12:20 to-js-data options validation
+
+## 修改概要
+
+- 将 `to-js-data` 的第二参数改为 options map，并保留旧 boolean `addColon` 参数的兼容警告。
+- 支持 `{} (:js-array true)`、`:js-object`、`:js-string`、`:js-number` 作为转换结果验证标记。
+- 为 JS 集成测试和 `cr query examples calcit.core/to-js-data` 增加 options 示例。
+
+## 验证
+
+- `yarn compile`
+- `cargo test -q --bin cr`
+- `yarn try-js`
+- `cr calcit/test.cirru query examples calcit.core/to-js-data`

package/editing-history/2026-07-26-1244-release-0.12.52.md

@@ -0,0 +1,12 @@
+# 2026-07-26 12:44 Release 0.12.52
+
+## 修改概要
+
+- 将 Rust crate 和 npm package 版本同步升级到 `0.12.52`。
+- 执行 `cargo update --workspace` 更新锁文件元数据。
+
+## 发布前验证
+
+- `yarn compile`
+- `cargo test -q --bin cr`
+- `yarn try-js`

package/editing-history/2026-07-26-1313-cli-long-option-hints.md

@@ -0,0 +1,14 @@
+# 2026-07-26 13:13 CLI 长参数提示修复
+
+## 修改概要
+
+- 将 `remote-libs readme` 的过时 `-f` 提示统一为 `--file`。
+- 修正 docs、edit、tree 与 markdown 提示中遗留的短参数，使用 CLI 当前公开的 `--filename`、`--context`、`--filter`、`--path`、`--code`、`--file`。
+
+## 验证
+
+- `cargo fmt --all`
+- `cargo run --bin cr -- docs remote-libs readme --help`
+- `cargo run --bin cr -- docs search --help`
+- `cargo run --bin cr -- query search --help`
+- `cargo run --bin cr -- tree show --help`

package/editing-history/2026-07-26-1341-method-display-literals.md

@@ -0,0 +1,5 @@
+# 方法字面量展示
+
+- `Calcit::Method` 的展示与 `turn_string` 统一输出 Calcit 可写的字面量语法，例如 `.ceil`、`.display-by`。
+- `defimpl` 与 `deftrait` 过去从 `format-to-lisp` 的 `(&invoke name)` 内部格式中截取方法名；展示改为 `.name` 后，需改为去掉首个点号并保留其余字符串。
+- 验证应覆盖 Rust 测试、JS 编译运行，以及 `cr eval '&methods-of 1'` 的实际输出，避免 trait/impl 方法名在预处理时退化为 tuple 方法调用。

package/editing-history/2026-07-26-2104-agent-semantic-interface-rfc.md

@@ -0,0 +1,11 @@
+# Agent semantic interface RFC
+
+## 概要
+
+- 新增 `07-26-agent-semantic-interface-roadmap-rfc.md`，系统整理 Snapshot AST、静态类型、文档知识图、结构化查询与事务编辑对 LLM Agent 的支撑路线。
+- 在 RFC 索引中登记新路线图。
+- 修正已有树形导航 RFC 中遗留的 `-p` 写法，统一为 `--path`。
+
+## 边界
+
+本批只固定后续开发方向和 CLI 词汇，不包含运行时或 Snapshot 数据变更。

package/editing-history/2026-07-26-2107-static-analysis-agent-cli.md

@@ -0,0 +1,30 @@
+# Static analysis and Agent CLI integration
+
+## 静态类型
+
+- 将 `:any` 定义为明确的静态顶类型，与会双向擦除检查的 `:dynamic` 区分。
+- 增强 list/map/set/ref、record/enum、callback、rest 参数与局部函数的类型推断和 schema 检查。
+- 让 type coverage/weak-types 输出稳定 JSON、详细路径、建议与 `--summary-only` 汇总。
+
+## Agent 语义查询
+
+- 增强 `cr query schema/type/type-at/context/search/search-expr`，提供带 revision 的机器可读结果。
+- 缩小查询时的 Snapshot/module 加载范围，并为定义 examples 增加精确检查入口。
+- 增加 `yarn check-agent-interface`，验证 JSON stdout 协议并记录查询耗时与输出体积。
+
+## CLI 编辑完整性
+
+- Cirru AST 输入严格使用 `quote` 作为代码/数据边界，不再把普通 EDN 误当代码。
+- `edit schema` 要求单个 quoted node；批量 `edit examples` 要求每个顶层节点独立 `quote`，从而同时可表示 leaf 和表达式。
+- `query examples` 直接显示 leaf；rename/move 定义时同步更新声明名称。
+- 清理文档与提示中的历史短参数，统一为明确的长参数词汇。
+
+## 验证
+
+- `cargo fmt --all`
+- `cargo test`
+- `cargo clippy -- -D warnings`
+- `yarn compile`
+- `yarn check-all`
+- `cr docs check-md docs/CalcitAgent.md --entry calcit/test.cirru --failures-only`
+- 通过 Snapshot 临时副本验证 schema/examples 的 quoted expression、quoted leaf 与裸输入拒绝路径。

package/editing-history/202607221613-remove-bundle-calcit-cli.md

@@ -0,0 +1,7 @@
+# Replace the legacy bundle CLI with a Calcit script
+
+- Removed the deprecated `bundle_calcit` Rust binary and its release artifact.
+- Added the recursive `read-dir` Calcit runtime API so filesystem workflows can be implemented in Calcit.
+- Added `calcit/bundle-calcit.cirru` as a directly executable snapshot that bundles indentation-based source files into a runnable snapshot.
+- Updated installation and bundle-mode documentation to use the script-based workflow.
+- Verified the script against `minimal-calcit`, including loading and running the generated snapshot.

package/editing-history/202607221944-replace-cr-sync-with-script.md

@@ -0,0 +1,7 @@
+# Replace the legacy cr-sync binary with a Calcit script
+
+- Removed the `cr-sync` Rust binary and its installation documentation.
+- Moved the bundle script to `calcit/scripts/` and added `sync-calcit.cirru` beside it.
+- Added `unix-time-ms` for script-generated snapshot metadata.
+- Reused `bisection-key` lexical-key APIs; `bisection-key` 0.0.18 fixes string-key append support.
+- Verified synchronization against the editor repository's real `compact.cirru` and `calcit.cirru` fixtures, then checked the output with the legacy dry-run binary.

package/editing-history/20260728-1500-caps-module-status.md

@@ -0,0 +1,17 @@
+# 2026-07-28 caps 模块状态检查与重置
+
+## 修改概要
+
+- 为 `caps` 增加 `status` 子命令，检查 `deps.cirru` 声明模块的版本、缺失状态和本地 Git 修改。
+- 为 `caps` 增加 `reset` 子命令，重置已安装模块的 tracked 本地修改。
+- 普通 `caps` 同步前增加本地模块状态提示。
+- 补充依赖加载文档。
+
+## 验证
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-all`
+- `yarn check-agent-interface`

package/editing-history/20260728-1501-release-0.12.53.md

@@ -0,0 +1,6 @@
+# 2026-07-28 发布 0.12.53
+
+## 修改概要
+
+- 同步 `Cargo.toml` 和 `package.json` 版本号到 `0.12.53`。
+- 执行 `cargo update --workspace` 更新 `Cargo.lock`。

package/editing-history/archived/2026-03-20-1229-query-window-3-with-parent-preview.md

@@ -60,13 +60,13 @@
   - 可见 `--detail-offset` 参数。
 - `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search --help`
   - `--start-path` 示例为点号格式。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 5`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state --filter respo.app.comp.todolist/comp-todolist --detail-offset 5`
   - 输出降噪，路径为点号，窗口外压缩。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 0`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state --filter respo.app.comp.todolist/comp-todolist --detail-offset 0`
   - 详情窗口为 `[0, 3)`，每条命中仅展示一行（优先父节点预览）。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state -f respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search state --filter respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
   - 精确命中不再把 `states` 视觉误判为 `state`；且不显示“add --exact”提示。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search-expr state -f respo.app.comp.todolist/comp-todolist --detail-offset 0`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search-expr state --filter respo.app.comp.todolist/comp-todolist --detail-offset 0`
   - 输出样式一致（单行预览）。
-- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search-expr state -f respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
+- `cargo run --bin cr -- /Users/jon.chen/repo/respo/respo/calcit.cirru query search-expr state --filter respo.app.comp.todolist/comp-todolist --detail-offset 0 --exact`
   - 结果为 `No matches found`，符合结构精确匹配预期。

package/editing-history/archived/2026-03-23-1137-command-echo-tool-output-cleanup.md

@@ -60,8 +60,8 @@
 - `cargo run --bin cr -- calcit/test.cirru analyze js-unescape 'demo_$q_'`
 - `cargo run --bin cr -- calcit/test.cirru query ns app.main`
 - `cargo run --bin cr -- calcit/test.cirru query find render`
-- `cargo run --bin cr -- calcit/test.cirru tree show app.main/test-json -p ''`
-- `cargo run --bin cr -- calcit/test.cirru docs search chunk -f agent-advanced.md`
+- `cargo run --bin cr -- calcit/test.cirru tree show app.main/test-json --path ''`
+- `cargo run --bin cr -- calcit/test.cirru docs search chunk --filename agent-advanced.md`
 - `cargo run --bin cr -- demos/calcit.cirru docs check-md docs/CalcitAgent.md`
 - `cargo run --bin cr -- /tmp/calcit-cli-demo/calcit.cirru tree replace ...` 多次人工检查 replace 输出形态
 

package/lib/calcit-data.d.mts

@@ -32,7 +32,7 @@ export declare let castTag: (x: CalcitValue) => CalcitTag;
 export declare var refsRegistry: Map<string, CalcitRef>;
 export declare let hashFunction: (x: CalcitValue) => Hash;
 export declare let toString: (x: CalcitValue, escaped: boolean, disableJsDataWarning?: boolean) => string;
-export declare let to_js_data: (x: CalcitValue, addColon?: boolean) => any;
+export declare let to_js_data: (x: CalcitValue, options?: CalcitValue | boolean) => any;
 export declare let _$n_map_$o_get: (xs: CalcitValue, k: CalcitValue) => CalcitValue;
 export declare let _$n__$e_: (x: CalcitValue, y: CalcitValue) => boolean;
 /** special trick for disabling ternary tree list check */

package/lib/calcit-data.mjs

@@ -441,7 +441,38 @@ export let toString = (x, escaped, disableJsDataWarning = false) => {
     }
     return `(#js ${JSON.stringify(x)})`;
 };
-export let to_js_data = (x, addColon = false) => {
+export let to_js_data = (x, options) => {
+    let addColon = false;
+    if (typeof options === "boolean") {
+        console.warn("to-js-data: the addColon boolean argument is deprecated; pass an options map instead");
+        addColon = options;
+    }
+    else if (options !== undefined) {
+        let jsOptions = to_js_data_inner(options, false);
+        addColon = jsOptions[":add-colon"] === true || jsOptions["add-colon"] === true;
+        let value = to_js_data_inner(x, addColon);
+        let expectedType = jsOptions[":type"] ??
+            jsOptions.type ??
+            (jsOptions[":js-array"] || jsOptions["js-array"] ? "js-array" : undefined) ??
+            (jsOptions[":js-string"] || jsOptions["js-string"] ? "js-string" : undefined) ??
+            (jsOptions[":js-number"] || jsOptions["js-number"] ? "js-number" : undefined) ??
+            (jsOptions[":js-object"] || jsOptions["js-object"] ? "js-object" : undefined) ??
+            "js-object";
+        let valid = (expectedType === "js-array" && Array.isArray(value)) ||
+            (expectedType === "js-object" &&
+                value !== null &&
+                typeof value === "object" &&
+                !Array.isArray(value) &&
+                !(value instanceof Set)) ||
+            (expectedType === "js-string" && typeof value === "string") ||
+            (expectedType === "js-number" && typeof value === "number");
+        if (!valid)
+            throw new Error(`to-js-data expects ${expectedType}`);
+        return value;
+    }
+    return to_js_data_inner(x, addColon);
+};
+let to_js_data_inner = (x, addColon) => {
     if (x == null) {
         return null;
     }
@@ -470,17 +501,17 @@ export let to_js_data = (x, addColon = false) => {
         return Symbol(x.value);
     }
     if (x instanceof CalcitTuple) {
-        var result = [to_js_data(x.tag)];
+        var result = [to_js_data_inner(x.tag, false)];
         for (let i = 0; i < x.extra.length; i++) {
             let item = x.extra[i];
-            result.push(to_js_data(item));
+            result.push(to_js_data_inner(item, false));
         }
         return result;
     }
     if (x instanceof CalcitList || x instanceof CalcitSliceList) {
         var result = [];
         for (let item of x.items()) {
-            result.push(to_js_data(item, addColon));
+            result.push(to_js_data_inner(item, addColon));
         }
         return result;
     }
@@ -490,22 +521,22 @@ export let to_js_data = (x, addColon = false) => {
         for (let idx = 0; idx < pairs.length; idx++) {
             let k = pairs[idx][0];
             let v = pairs[idx][1];
-            var key = to_js_data(k, addColon);
-            result[key] = to_js_data(v, addColon);
+            var key = to_js_data_inner(k, addColon);
+            result[key] = to_js_data_inner(v, addColon);
         }
         return result;
     }
     if (x instanceof CalcitSet) {
         let result = new Set();
         x.values().forEach((v) => {
-            result.add(to_js_data(v, addColon));
+            result.add(to_js_data_inner(v, addColon));
         });
         return result;
     }
     if (x instanceof CalcitRecord) {
         let result = {};
         for (let idx = 0; idx < x.fields.length; idx++) {
-            result[x.fields[idx].value] = to_js_data(x.values[idx]);
+            result[x.fields[idx].value] = to_js_data_inner(x.values[idx], false);
         }
         return result;
     }

package/lib/calcit.procs.d.mts

@@ -20,6 +20,7 @@ export declare const calcit_package_json: {
         "bench-recur-smoke": string;
         "check-smooth": string;
         "check-all": string;
+        "check-agent-interface": string;
         "try-all": string;
         "try-rs": string;
         "warn-dyn-method": string;

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.51",
+    "version": "0.12.53",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.7.0",
@@ -18,7 +18,8 @@
         "test-snippets": "cargo test -q snippets::tests",
         "bench-recur-smoke": "cargo run --bin cr -- calcit/test.cirru js && node --input-type=module -e \"import { test_loop } from './js-out/test-recursion.main.mjs'; const n=3000; const t0=process.hrtime.bigint(); for(let i=0;i<n;i++) test_loop(); const dt=Number(process.hrtime.bigint()-t0)/1e6; console.log('test_loop_ms='+dt.toFixed(3));\"",
         "check-smooth": "yarn fmt-rs && yarn lint-rs && yarn test-rs && yarn check-all",
-        "check-all": "yarn compile && yarn try-rs && yarn try-js && yarn try-ir && yarn try-wasm",
+        "check-all": "yarn compile && yarn check-agent-interface && yarn try-rs && yarn try-js && yarn try-ir && yarn try-wasm",
+        "check-agent-interface": "cargo build --bin cr && node scripts/check-agent-interface.mjs",
         "try-all": "yarn check-all",
         "try-rs": "cargo run --bin cr -- calcit/test.cirru",
         "warn-dyn-method": "cargo run --bin cr -- calcit/test.cirru --warn-dyn-method",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.51",
+  "version": "0.12.53",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.7.0",
@@ -18,7 +18,8 @@
     "test-snippets": "cargo test -q snippets::tests",
     "bench-recur-smoke": "cargo run --bin cr -- calcit/test.cirru js && node --input-type=module -e \"import { test_loop } from './js-out/test-recursion.main.mjs'; const n=3000; const t0=process.hrtime.bigint(); for(let i=0;i<n;i++) test_loop(); const dt=Number(process.hrtime.bigint()-t0)/1e6; console.log('test_loop_ms='+dt.toFixed(3));\"",
     "check-smooth": "yarn fmt-rs && yarn lint-rs && yarn test-rs && yarn check-all",
-    "check-all": "yarn compile && yarn try-rs && yarn try-js && yarn try-ir && yarn try-wasm",
+    "check-all": "yarn compile && yarn check-agent-interface && yarn try-rs && yarn try-js && yarn try-ir && yarn try-wasm",
+    "check-agent-interface": "cargo build --bin cr && node scripts/check-agent-interface.mjs",
     "try-all": "yarn check-all",
     "try-rs": "cargo run --bin cr -- calcit/test.cirru",
     "warn-dyn-method": "cargo run --bin cr -- calcit/test.cirru --warn-dyn-method",

package/ts-src/calcit-data.mts

@@ -472,7 +472,39 @@ export let toString = (x: CalcitValue, escaped: boolean, disableJsDataWarning: b
   return `(#js ${JSON.stringify(x)})`;
 };
 
-export let to_js_data = (x: CalcitValue, addColon: boolean = false): any => {
+export let to_js_data = (x: CalcitValue, options?: CalcitValue | boolean): any => {
+  let addColon = false;
+  if (typeof options === "boolean") {
+    console.warn("to-js-data: the addColon boolean argument is deprecated; pass an options map instead");
+    addColon = options;
+  } else if (options !== undefined) {
+    let jsOptions = to_js_data_inner(options, false) as Record<string, any>;
+    addColon = jsOptions[":add-colon"] === true || jsOptions["add-colon"] === true;
+    let value = to_js_data_inner(x, addColon);
+    let expectedType =
+      jsOptions[":type"] ??
+      jsOptions.type ??
+      (jsOptions[":js-array"] || jsOptions["js-array"] ? "js-array" : undefined) ??
+      (jsOptions[":js-string"] || jsOptions["js-string"] ? "js-string" : undefined) ??
+      (jsOptions[":js-number"] || jsOptions["js-number"] ? "js-number" : undefined) ??
+      (jsOptions[":js-object"] || jsOptions["js-object"] ? "js-object" : undefined) ??
+      "js-object";
+    let valid =
+      (expectedType === "js-array" && Array.isArray(value)) ||
+      (expectedType === "js-object" &&
+        value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof Set)) ||
+      (expectedType === "js-string" && typeof value === "string") ||
+      (expectedType === "js-number" && typeof value === "number");
+    if (!valid) throw new Error(`to-js-data expects ${expectedType}`);
+    return value;
+  }
+  return to_js_data_inner(x, addColon);
+};
+
+let to_js_data_inner = (x: CalcitValue, addColon: boolean): any => {
   if (x == null) {
     return null;
   }
@@ -501,17 +533,17 @@ export let to_js_data = (x: CalcitValue, addColon: boolean = false): any => {
     return Symbol(x.value);
   }
   if (x instanceof CalcitTuple) {
-    var result: any[] = [to_js_data(x.tag)];
+    var result: any[] = [to_js_data_inner(x.tag, false)];
     for (let i = 0; i < x.extra.length; i++) {
       let item = x.extra[i];
-      result.push(to_js_data(item));
+      result.push(to_js_data_inner(item, false));
     }
     return result;
   }
   if (x instanceof CalcitList || x instanceof CalcitSliceList) {
     var result: any[] = [];
     for (let item of x.items()) {
-      result.push(to_js_data(item, addColon));
+      result.push(to_js_data_inner(item, addColon));
     }
     return result;
   }
@@ -521,22 +553,22 @@ export let to_js_data = (x: CalcitValue, addColon: boolean = false): any => {
     for (let idx = 0; idx < pairs.length; idx++) {
       let k = pairs[idx][0];
       let v = pairs[idx][1];
-      var key = to_js_data(k, addColon);
-      result[key] = to_js_data(v, addColon);
+      var key = to_js_data_inner(k, addColon);
+      result[key] = to_js_data_inner(v, addColon);
     }
     return result;
   }
   if (x instanceof CalcitSet) {
     let result = new Set();
     x.values().forEach((v) => {
-      result.add(to_js_data(v, addColon));
+      result.add(to_js_data_inner(v, addColon));
     });
     return result;
   }
   if (x instanceof CalcitRecord) {
     let result: Record<string, CalcitValue> = {};
     for (let idx = 0; idx < x.fields.length; idx++) {
-      result[x.fields[idx].value] = to_js_data(x.values[idx]);
+      result[x.fields[idx].value] = to_js_data_inner(x.values[idx], false);
     }
     return result;
   }