@calcit/procs 0.12.29 → 0.12.31

package/build.rs

@@ -104,6 +104,14 @@ fn map_key_path_segment(key: &Edn) -> String {
 
 /// 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> {
+  // Simple scalar schemas (e.g. :dynamic, :nil) are valid as-is — skip Cirru path
+  match value {
+    Edn::Tag(_) | Edn::Nil => {
+      validate_schema_edn_no_legacy_quotes(value, owner)?;
+      return Ok(value.clone());
+    }
+    _ => {}
+  }
   // 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())

package/editing-history/202604251940-wasm-suite-multi-module-entry.md

@@ -0,0 +1,53 @@
+# 202604251940 — wasm: 新增 test-wasm-suite 多模块入口
+
+## 背景
+
+`test-wasm.cirru` 是手写的小型 WASM 测试用例集，已经通过；但
+`yarn check-all` 还会运行 `calcit/test-X.cirru` 一系列测试模块
+（test-cond / test-math / test-set / ...），目前 WASM target
+还没有专门的入口把这些测试统一跑起来。
+
+## 改动
+
+1. 新增 `calcit/test-wasm-suite.cirru`：手写的 snapshot 文件，
+   通过 `:modules` 引入 `util.cirru` 与若干测试模块，自身定义
+   `test-wasm-suite.main/main!` 依次调用各测试模块的 `main!`。
+   - 当前包含：`util` + `test-cond` + `test-math` + `test-set` + `test-tuple`
+   - `test-tuple/main!` 因 `&tuple:enum` 未实现，被 codegen 标为
+     skip，main! 会以 `f64 0.0` 占位返回，对整体不产生副作用。
+2. 新增 `scripts/test-wasm-suite-extended.sh`：编译并运行新入口的
+   一键脚本，输出 `[wasm] skipping ...` 的列表，便于后续逐步补齐
+   proc 实现。
+
+## 已知阻塞（短期不放进新入口）
+
+- `test-recursion`：`emit_bump_alloc` 与 closure-as-value 的交互产生
+  无效 WAT（`global.set __heap_ptr` 收到 f64），独立编译也会触发；
+  与目前 in-progress refactor（emit_set_find_structural / hash_list_or_set）
+  联动后表现尤其明显。
+- `test-list`：`local.set f64` 收到 i32（function 35 体内），bytes 模式
+  形如 `local.get a (i32) ; local.get b (i32) ; local.set c (f64)`。
+- `test-string`：`includes?` / `.find-index` / `starts-with?` /
+  `strip-prefix` / `strip-suffix` 等字符串过程 WASM 未实现；
+  `trim` / `blank?` / `parse-float` / `&str:replace` / `format-to-cirru` /
+  `&cirru-quote:to-list` / `get-char-code` 同上。
+- `test-fn`：`(let f2 &+)` 把过程作为值放进局部变量，
+  当前 WASM 不支持 first-class proc，整个 `main!` 会被 skip。
+- `test-algebra`、`test-map`：旧的 `unreachable` 失败，与本次改动无关。
+
+## 用法
+
+```bash
+bash scripts/test-wasm-suite-extended.sh
+# 期望最后一行: [test-wasm-suite] PASS
+```
+
+## 后续步骤
+
+1. 修 test-recursion 的 closure-as-value / bump_alloc 类型不一致
+   （定位 `f64.const 0; local.tee Xf64; global.set __heap_ptr` 来源）。
+2. 修 test-list 的 i32 ↔ f64 binding bug。
+3. 实现 `includes?` / `starts-with?` / `ends-with?` / `strip-prefix` /
+   `strip-suffix` / `.find-index` 等 string proc，把 test-string 的
+   `test-includes` 子集放进新入口。
+4. 实现 `&tuple:enum` 等 tuple 操作，让 test-tuple/main! 不再被 skip。

package/editing-history/202604252003-wasm-method-includes-string-and-set-refactor.md

@@ -0,0 +1,71 @@
+# 202604252003 — WASM suite extended: .includes? string branch + uncommitted refactor consolidation
+
+## Background
+
+In the previous session a multi-module WASM suite entry (`calcit/test-wasm-suite.cirru`) was added
+to gradually exercise more of the existing `calcit/test-*.cirru` programs against the WASM codegen.
+At that point a sizable in-progress refactor in `src/codegen/emit_wasm/{heap,hof,lists,runtime,sets}.rs`
+was left uncommitted alongside, and `test-string.cirru` was deferred because folding it into the
+suite triggered an `unreachable` trap.
+
+## Findings this round
+
+When folding `test-string.main` into `test-wasm-suite.main/main!`, the runtime trap reproduced. By
+calling individual exports (new helper `scripts/test-wasm-call.mjs`) it was clear that:
+
+1. `(.includes? "abc" "abc")` returned `0` (false) instead of `1`. Root cause:
+   `methods::emit_method_includes` only handled `list/map/set` receivers; for any other type it
+   emitted `f64_const(0.0)` as the fallback. Strings therefore never reached
+   `__rt_str_find_index`.
+2. After fixing #1, `test-includes` still trapped — the assertions
+   `assert= true $ starts-with? :a/b :a/` and `assert= true $ starts-with? :a/b |a/` pass
+   tags as arguments. Tags in WASM are encoded as small `f64` values equal to their tag-index id,
+   so `__rt_str_starts_with` reads them as bogus heap pointers and silently returns 0. Adding tag→
+   string conversion at runtime is a follow-up.
+3. `test-bitwise` traps on `&number:display-by` (radix formatting) which is currently stubbed to
+   return `0`.
+
+Because #2 and #3 require additional runtime helpers, `test-string.cirru` is left out of the suite
+for this commit. The `.includes?` regression is fixed in isolation; it also benefits any other
+program that calls `.includes?` on a string.
+
+## Changes in this commit
+
+- `src/codegen/emit_wasm/methods.rs`: extend `emit_method_includes` with a string branch
+  (`emit_str_includes_from_local`) that calls `__rt_str_find_index >= 0`.
+- `scripts/test-wasm-call.mjs`: minimal helper to invoke a single named export against the latest
+  `js-out/program.wasm`, useful for bisecting which assertion in a `main!` traps.
+
+The commit also folds in the previously-uncommitted refactor that landed in
+`src/codegen/emit_wasm/{heap,hof,lists,runtime,sets}.rs`:
+
+- `sets.rs`: `emit_set_find_structural` replaces the pointer-only `__rt_set_find_elem` for
+  `difference`/`intersection`/set-equality so identical-by-content elements are treated as equal.
+- `runtime.rs`: new `__rt_hash_list_or_set(ptr) -> i32` (XOR-based content hash) plus a couple of
+  new helper-function indices.
+- `hof.rs`: `emit_copy_type_tag` so `map`/`filter` preserve the receiver tag (set→set, list→list).
+- `lists.rs`: `range start end step` 3-arg form.
+- `heap.rs`: smarter `emit_hash_proc` that detects heap pointers at runtime and dispatches to the
+  list/set hash helper. The dead `emit_hash_expr_i32`/`emit_hash_mix` static helpers are removed.
+- `emit_wasm.rs`: `#[allow(private_interfaces)]` on `emit_equals_core` and
+  `emit_equals_core_shallow` (both already returned a `pub(super)`-only opaque local index but are
+  used from sibling modules through the `super::*` re-export).
+
+## Verification
+
+```bash
+bash scripts/cargo-with-sdk.sh clippy --bin cr-wasm -- -D warnings   # clean
+bash scripts/cargo-with-sdk.sh build  --bin cr-wasm --release        # ok
+bash scripts/test-wasm-suite-extended.sh                             # PASS
+bash scripts/test-wasm-suite.sh                                      # 6/10 (unchanged)
+```
+
+`scripts/test-wasm-suite.sh` skips `test-fn`, `test-string`, `test-tuple`, `test-list` for the
+same reasons documented previously; that is independent of this commit.
+
+## Follow-ups
+
+1. Tag → string conversion at runtime so string procs accept tags (unblocks `test-string`).
+2. `&number:display-by` radix formatting (unblocks the last 3 assertions in `test-bitwise`).
+3. The other test-string skips (`&str:replace`, `parse-float`, `blank?`, `trim`,
+   `get-char-code`, `format-to-cirru`, `&cirru-quote:to-list`).

package/editing-history/202604252010-wasm-suite-add-fn-lens-edn.md

@@ -0,0 +1,43 @@
+# 202604252010 — WASM suite extended: + test-fn / test-lens / test-edn
+
+## Background
+
+After landing the `.includes?` string fix, this round adds three more `test-*.cirru` programs to
+`calcit/test-wasm-suite.cirru` to cover more of the WASM runtime surface. Goal: keep growing the
+"runs end-to-end in WASM" set without depending on Host FFI features.
+
+## Process
+
+For each candidate module:
+
+1. Inspect `cr-wasm <module>.cirru` standalone to enumerate `[wasm] skipping ...` lines (these are
+   per-def errors that cause that def to be replaced with a `0.0`-returning stub).
+2. Read the module's `main!` body to confirm trapping assertions can survive when the skipped
+   helpers return `0`.
+3. Add to the suite, rebuild, and run `bash scripts/test-wasm-suite-extended.sh`.
+
+## Result
+
+Suite now covers (in addition to previous `test-cond/test-math/test-set/test-tuple`):
+
+- `test-fn` — only `&init-builtin-impls!` skipped; suite passes cleanly.
+- `test-lens` — `test-lens.main/test-lens` is skipped (`:::` rejects a quoted form arg) but other
+  defs in the module compile; `main!` does not trip the stub.
+- `test-edn` — many sub-tests skipped (`parse-cirru-edn`, `trim`, `&extract-code-into-edn`), but
+  the skipped fns return `0` instead of running their assertions, so `main!` completes.
+
+Modules tried but reverted:
+
+- `test-string` — assertions feed tags into `starts-with?`/`ends-with?`/`includes?`. Tags in WASM
+  are encoded as small `f64` ids (their tag-index value), not heap string pointers, so the procs
+  silently return `0` and the assertion traps. Needs a tag→string runtime helper.
+- `test-algebra` — `test-map` exercises `%{} AlgebraBox`, `assert-traits`, `.map` on records, and
+  `:value` access; record/trait dispatch is not yet implemented in WASM.
+- `test-map` (the standalone, full map suite) — `test-pairs`/`test-keys` etc. compile but trap at
+  runtime, likely from map iteration ordering or hash collision behavior. Needs deeper triage.
+
+## Verification
+
+```bash
+bash scripts/test-wasm-suite-extended.sh   # PASS (8 modules including util)
+```

package/editing-history/202604252051-display-by.md

@@ -0,0 +1,39 @@
+# `&number:display-by` WASM 实现
+
+## 摘要
+
+实现了 `&number:display-by` 和 `.display-by` 方法的 WASM codegen，支持二进制、八进制、十六进制格式化，并将 `test-string` 模块加入 WASM 扩展测试套件。
+
+## 关键实现点
+
+### `build_rt_display_by` (runtime.rs)
+
+- 函数签名: `(value: f64, radix: f64) -> f64` (返回字符串堆 ptr)
+- 算法：负数检测 → 计数位数（div 循环）→ 计算前缀长度（radix ∈ {2,8,16} → 2, else 0）→ 分配堆字符串 → 写前缀（`0b`/`0o`/`0x`）→ 从右往左写位数（`'0'..digit` 或 `'a'..digit-10`）
+- locals 索引 2-16，手动分配（非 RuntimeFnBuilder 风格）
+- 负数：先检测，计数时用 abs_i64，最后写 '-'
+
+### 注意
+
+- 必须先用 `collect_strings_from_expr` 收集 tag 名称才能支持 tag→string（前一次提交已做）
+- local 参数：value=0, radix=1；其余 2..16 为局部变量
+
+### 测试
+
+- `test-display-by-bin()` = 7 (17 → "0b10001")
+- `test-display-by-hex()` = 4 (17 → "0x11")
+- test-string 模块加入 test-wasm-suite（8个模块），全部 PASS
+
+## 修改文件
+
+- `src/codegen/emit_wasm/runtime.rs` — 新增 `build_rt_display_by` + 注册 `__rt_display_by`
+- `src/codegen/emit_wasm.rs` — 分拆 `NativeNumberDisplayBy` 从 stub 到 `call_rt("__rt_display_by")`
+- `src/codegen/emit_wasm/methods.rs` — 新增 `.display-by` 方法分发
+- `calcit/test-wasm-suite.cirru` — 加入 `test-string`
+- `calcit/test-wasm.cirru` — 新增 `test-display-by-bin` / `test-display-by-hex`
+- `scripts/test-wasm.mjs` — 新增对应断言
+
+## 后续计划
+
+- `trim`、`blank?`、`&str:replace`、`parse-float`、`get-char-code`
+- HOF closures-as-values (S1 fn-table)

package/editing-history/202604281728-fix-gensym-stable.md

@@ -0,0 +1,31 @@
+# Fix: Gensym 稳定性问题
+
+## 问题描述
+
+`cr js` 每次运行会生成不同的 JS 文件，原因是 gensym 计数器不稳定（如 `v__1` 变成 `v__3`）。
+
+## 根本原因
+
+Calcit 的 gensym 使用 `NS_SYMBOL_DICT: HashMap<Arc<str>, usize>` 记录计数器。由于 Rust 的 `HashMap` 每进程随机化迭代顺序，不同运行时的 def 编译顺序不同，导致 gensym 计数器累积值不一样。
+
+有**两条**编译路径，只修了一条是不够的：
+1. `ensure_ns_def_preprocessed` —— 正常编译路径，通过 `with_compiling_def` 重置 gensym 计数器（之前已修）
+2. `compile_source_def_for_snapshot` —— 快照填充路径（JS codegen 时触发），**缺少 `with_compiling_def` 包装**，导致 `CURRENT_COMPILING_DEF` 为 `None`，gensym 退回到 `file_ns`（命名空间级 key），计数器跨 def 累积
+
+## 修复方法
+
+在 `src/runner/preprocess/mod.rs` 的 `compile_source_def_for_snapshot` 函数中，为 `preprocess_expr` 调用加上 `builtins::meta::with_compiling_def(ns, def, ...)` 包装，与 `ensure_ns_def_preprocessed` 保持一致。
+
+## 已修改文件
+
+- `src/builtins/syntax.rs`: gensym key 改为 `CURRENT_COMPILING_DEF`（无 `file_ns` 前缀）
+- `src/builtins/meta.rs`: 新增 `CURRENT_COMPILING_DEF` thread_local + `with_compiling_def`（自动重置计数器）
+- `src/runner/preprocess/mod.rs`:
+  - `ensure_ns_def_preprocessed`: 包 `with_compiling_def`（第一次修）
+  - `compile_source_def_for_snapshot`: 包 `with_compiling_def`（本次修）
+
+## 验证
+
+- `cr js` 连续 8 次运行，无任何文件变化
+- `cargo test` 67 passed
+- `yarn check-all` 全部通过

package/editing-history/202604291400-fix-bind-type-precompile.md

@@ -0,0 +1,38 @@
+# Fix: bind-type 类型槽预编译顺序问题
+
+## 问题描述
+
+`cr js` 在 tiye-index 项目中，`reel.app.comp.todolist.mjs` 和 `respo.schema.mjs` 仍然不稳定——有时生成 `Op`-aware 版本（带 `import { Op }` 和 `$clt._PCT__$o__$o_(Op, ...)`），有时生成不带 Op 的版本（使用 `$clt._$o__$o_(...)`）。
+
+## 根本原因
+
+`bind-type :dispatch-op Op` 在 `respo.main/main!` 函数体中，是一个预处理阶段的副作用操作：当 `preprocess_expr` 遇到 `bind-type` 调用时，立即执行 `bind_type_slot("dispatch-op", Op)`，使 `*dispatch-op` 类型槽指向 Op 枚举。
+
+问题根源：`reel.app.comp.todolist` 等组件 def 会作为入口函数 `app.main/main!` 的传递依赖被提前编译。由于 HashMap 迭代顺序不确定，某些运行中 `todolist` 在 `respo.main/main!` 之前编译——此时 `*dispatch-op` 类型槽尚未绑定，导致 `d! $ :: :states cursor ...` 中的元组字面量无法被改写为 `%:: Op :states cursor ...`，生成结构上不同的 JS 代码。
+
+## 修复方法
+
+**双重修复：**
+
+### 1. 预处理阶段：`precompile_bind_type_defs` (主要修复)
+
+在 `src/lib.rs` 的 `run_program_with_docs` 中，在开始主入口预处理之前，先扫描**所有**程序源代码，找出含有 `bind-type` 调用的 def，并提前编译它们。
+
+这确保 `respo.main/main!`（含 `bind-type :dispatch-op Op`）在 `app.main/main!` 的依赖树遍历之前被编译，从而使 `:dispatch-op` 类型槽在所有组件编译前就已绑定。
+
+### 2. 快照填充阶段：任务排序 (辅助修复)
+
+在 `src/program.rs` 的 `collect_snapshot_fill_tasks` 中，对快照填充任务排序，确保含 `bind-type` 的 def 在快照阶段也优先处理，同时按 (ns, def) 字典序排序保证完全确定性。
+
+## 已修改文件
+
+- `src/lib.rs`: 在 `run_program_with_docs` 中调用新增的 `precompile_bind_type_defs`
+- `src/runner/preprocess/mod.rs`: 新增 `precompile_bind_type_defs` 公开函数（扫描所有源 def，提前编译含 `bind-type` 的 def）
+- `src/program.rs`:
+  - `calcit_contains_bind_type` 改为 `pub fn`（供 preprocess 模块使用）
+  - `collect_snapshot_fill_tasks` 中对任务排序（bind-type 优先，其余按字典序）
+
+## 验证
+
+- `cr js` 在 tiye-index 项目连续 8 次运行，第 1 次（旧输出重新生成）后无任何文件变化
+- `cargo test --lib` 179 tests passed

package/lib/calcit.procs.mjs

@@ -25,6 +25,7 @@ export * from "./custom-formatter.mjs";
 export * from "./js-cirru.mjs";
 export * from "./js-arity-helpers.mjs";
 export * from "./js-tag-helpers.mjs";
+export * from "./js-buf-list.mjs";
 export { _$n_compare } from "./js-primes.mjs";
 import { CalcitList, CalcitSliceList, foldl } from "./js-list.mjs";
 import { CalcitMap, CalcitSliceMap } from "./js-map.mjs";
@@ -299,48 +300,6 @@ export function _$n_record_$o_nth(x, idx) {
         throw new Error(`&record:nth index ${i} out of range for record with ${x.values.length} fields`);
     return x.values[i];
 }
-// === BufList — mutable append-only list ===
-// Wrapper around a plain JS Array for O(1) push.
-export class CalcitBufList {
-    constructor(buf) {
-        this.buf = buf ?? [];
-    }
-}
-export function _$n_buf_list_$o_new() {
-    return new CalcitBufList();
-}
-export function _$n_buf_list_$o_push(buf, item) {
-    if (!(buf instanceof CalcitBufList))
-        throw new Error(`&buf-list:push expected a buf-list, got ${buf}`);
-    buf.buf.push(item);
-    return buf;
-}
-export function _$n_buf_list_$o_concat(buf, xs) {
-    if (!(buf instanceof CalcitBufList))
-        throw new Error(`&buf-list:concat expected a buf-list, got ${buf}`);
-    if (xs instanceof CalcitSliceList || xs instanceof CalcitList) {
-        const gen = xs.items();
-        let next = gen.next();
-        while (!next.done) {
-            buf.buf.push(next.value);
-            next = gen.next();
-        }
-    }
-    else {
-        throw new Error(`&buf-list:concat expected a list, got ${xs}`);
-    }
-    return buf;
-}
-export function _$n_buf_list_$o_to_list(buf) {
-    if (!(buf instanceof CalcitBufList))
-        throw new Error(`&buf-list:to-list expected a buf-list, got ${buf}`);
-    return new CalcitSliceList([...buf.buf]);
-}
-export function _$n_buf_list_$o_count(buf) {
-    if (!(buf instanceof CalcitBufList))
-        throw new Error(`&buf-list:count expected a buf-list, got ${buf}`);
-    return buf.buf.length;
-}
 export function _$n_set_$o_count(x) {
     if (x instanceof CalcitSet)
         return x.len();
@@ -2002,6 +1961,38 @@ export let _$n_map_$o_common_keys = (a, b) => {
         throw new Error("expected 2 maps");
     }
 };
+/** Single-pass diff: returns [drop-keys, new-diff, common-triples] in two traversals instead of 3+ */
+export let _$n_map_$o_diff_triple = (a, b) => {
+    if ((a instanceof CalcitMap || a instanceof CalcitSliceMap) && (b instanceof CalcitMap || b instanceof CalcitSliceMap)) {
+        let dropKeys = [];
+        let commonTriples = [];
+        // One pass over a: split into drop-keys and common-triples
+        let aKeys = a.keysArray();
+        for (let i = 0; i < aKeys.length; i++) {
+            let k = aKeys[i];
+            if (b.contains(k)) {
+                commonTriples.push(new CalcitSliceList([k, a.get(k), b.get(k)]));
+            }
+            else {
+                dropKeys.push(k);
+            }
+        }
+        // One pass over b: collect entries not in a
+        let newDiffPairs = [];
+        let bKeys = b.keysArray();
+        for (let i = 0; i < bKeys.length; i++) {
+            let k = bKeys[i];
+            if (!a.contains(k)) {
+                newDiffPairs.push(k);
+                newDiffPairs.push(b.get(k));
+            }
+        }
+        return new CalcitSliceList([new CalcitSet(dropKeys), new CalcitSliceMap(newDiffPairs), new CalcitSliceList(commonTriples)]);
+    }
+    else {
+        throw new Error("&map:diff-triple expected 2 maps");
+    }
+};
 export let bit_shr = (base, step) => {
     return base >> step;
 };

package/lib/js-buf-list.mjs

@@ -0,0 +1,44 @@
+import { CalcitList, CalcitSliceList } from "./js-list.mjs";
+// === CalcitBufList — mutable append-only list ===
+// Wrapper around a plain JS Array for O(1) push.
+// Use &buf-list:new / &buf-list:push / &buf-list:to-list in Calcit code.
+export class CalcitBufList {
+    constructor(buf) {
+        this.buf = buf ?? [];
+    }
+}
+export function _$n_buf_list_$o_new() {
+    return new CalcitBufList();
+}
+export function _$n_buf_list_$o_push(buf, item) {
+    if (!(buf instanceof CalcitBufList))
+        throw new Error(`&buf-list:push expected a buf-list, got ${buf}`);
+    buf.buf.push(item);
+    return buf;
+}
+export function _$n_buf_list_$o_concat(buf, xs) {
+    if (!(buf instanceof CalcitBufList))
+        throw new Error(`&buf-list:concat expected a buf-list, got ${buf}`);
+    if (xs instanceof CalcitSliceList || xs instanceof CalcitList) {
+        const gen = xs.items();
+        let next = gen.next();
+        while (!next.done) {
+            buf.buf.push(next.value);
+            next = gen.next();
+        }
+    }
+    else {
+        throw new Error(`&buf-list:concat expected a list, got ${xs}`);
+    }
+    return buf;
+}
+export function _$n_buf_list_$o_to_list(buf) {
+    if (!(buf instanceof CalcitBufList))
+        throw new Error(`&buf-list:to-list expected a buf-list, got ${buf}`);
+    return new CalcitSliceList([...buf.buf]);
+}
+export function _$n_buf_list_$o_count(buf) {
+    if (!(buf instanceof CalcitBufList))
+        throw new Error(`&buf-list:count expected a buf-list, got ${buf}`);
+    return buf.buf.length;
+}

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.29",
+    "version": "0.12.31",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",
@@ -32,7 +32,7 @@
         "url": "git+https://github.com/calcit-lang/calcit.git"
     },
     "dependencies": {
-        "@calcit/ternary-tree": "0.0.25",
+        "@calcit/ternary-tree": "0.0.26",
         "@cirru/parser.ts": "^0.0.9",
         "@cirru/writer.ts": "^0.1.7"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.29",
+  "version": "0.12.31",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",
@@ -32,7 +32,7 @@
     "url": "git+https://github.com/calcit-lang/calcit.git"
   },
   "dependencies": {
-    "@calcit/ternary-tree": "0.0.25",
+    "@calcit/ternary-tree": "0.0.26",
     "@cirru/parser.ts": "^0.0.9",
     "@cirru/writer.ts": "^0.1.7"
   },

package/rfc/04-13-call-arg-literal-rewrite-rfc.md

@@ -36,12 +36,13 @@ sum-point $ %{} Point (:x 10) (:y 20)
 
 预处理器根据函数参数的 schema 类型标注，自动将简写形式改写为完整形式：
 
-| 简写 | 改写为 | 触发条件 |
-|---|---|---|
+| 简写               | 改写为                    | 触发条件                 |
+| ------------------ | ------------------------- | ------------------------ |
 | `{} (:x 1) (:y 2)` | `%{} Point (:x 1) (:y 2)` | 参数类型为 struct/record |
-| `:: :ok` | `%:: Result0 :ok` | 参数类型为 enum |
+| `:: :ok`           | `%:: Result0 :ok`         | 参数类型为 enum          |
 
 改写后的 AST 能正常参与：
+
 - 运行时类型验证（field 校验、variant 校验）
 - 预处理阶段类型检查（`check_user_fn_arg_types`）
 - JS codegen（通过 Import 引用而非内联 Struct/Enum 值）
@@ -75,12 +76,15 @@ sum-point $ %{} Point (:x 10) (:y 20)
 defstruct Point (:x :number) (:y :number)
 
 defn sum-point (p)
-  :: :fn $ {} (:return :number)
-    :args $ [] 'app.main/Point
   &+ (:x p) (:y p)
 
+;; :schema 中标注参数类型
+:: :fn $ {} (:return :number)
+  :args $ [] 'app.main/Point
+
 ;; 简写
 sum-point $ {} (:x 10) (:y 20)
+
 ;; 预处理改写为
 sum-point $ %{} Point (:x 10) (:y 20)
 ```
@@ -109,10 +113,12 @@ sum-point $ %{} Point (:x 10) (:y 20)
 defenum Result0 (:err :string) (:ok)
 
 defn takes-result (r)
-  :: :fn $ {} (:return :dynamic)
-    :args $ [] 'app.main/Result0
   tag-match r ((:ok) :ok) ((:err msg) msg) $ _ :unknown
 
+;; :schema 中标注参数类型
+:: :fn $ {} (:return :dynamic)
+  :args $ [] 'app.main/Result0
+
 ;; 简写
 takes-result $ :: :ok
 ;; 预处理改写为
@@ -130,28 +136,28 @@ takes-result $ %:: Result0 :err |error-msg
 
 在 `CalcitTypeAnnotation` 上新增方法：
 
-| 方法 | 用途 |
-|---|---|
+| 方法                           | 用途                                      |
+| ------------------------------ | ----------------------------------------- |
 | `resolve_to_struct_with_ref()` | 解析 struct + 可选 (ns, def) 路径（已有） |
-| `resolve_to_enum_with_ref()` | 解析 enum + 可选 (ns, def) 路径（新增） |
+| `resolve_to_enum_with_ref()`   | 解析 enum + 可选 (ns, def) 路径（新增）   |
 
 两者都处理 `Struct/Record`↔`Enum/Tuple` 直接值、`TypeRef("ns/def")` 程序查找、以及 `Optional(inner)` 解包。
 
 底层依赖：
 
-| 函数 | 用途 |
-|---|---|
+| 函数                                   | 用途                                         |
+| -------------------------------------- | -------------------------------------------- |
 | `resolve_struct_from_program(ns, def)` | 从 program registry 查找 struct 定义（已有） |
-| `resolve_enum_from_program(ns, def)` | 从 program registry 查找 enum 定义（新增） |
+| `resolve_enum_from_program(ns, def)`   | 从 program registry 查找 enum 定义（新增）   |
 
 ### 4.2 改写函数
 
-| 函数 | 用途 |
-|---|---|
-| `try_rewrite_map_args_to_records()` | 遍历参数列表，对 map 字面量尝试改写（已有） |
-| `try_rewrite_single_map_to_record()` | 单个参数的 map→record 改写（已有） |
-| `try_rewrite_tuple_args_to_enum_tuples()` | 遍历参数列表，对 tuple 字面量尝试改写（新增） |
-| `try_rewrite_single_tuple_to_enum_tuple()` | 单个参数的 tuple→enum-tuple 改写（新增） |
+| 函数                                       | 用途                                          |
+| ------------------------------------------ | --------------------------------------------- |
+| `try_rewrite_map_args_to_records()`        | 遍历参数列表，对 map 字面量尝试改写（已有）   |
+| `try_rewrite_single_map_to_record()`       | 单个参数的 map→record 改写（已有）            |
+| `try_rewrite_tuple_args_to_enum_tuples()`  | 遍历参数列表，对 tuple 字面量尝试改写（新增） |
+| `try_rewrite_single_tuple_to_enum_tuple()` | 单个参数的 tuple→enum-tuple 改写（新增）      |
 
 ### 4.3 集成点
 
@@ -169,18 +175,19 @@ takes-result $ %:: Result0 :err |error-msg
 改写时若从 `TypeRef` 解析出 (ns, def) 路径，会构造 `Calcit::Import` 而非内联的 `Calcit::Struct`/`Calcit::Enum`。这是因为 JS codegen 不支持直接 emit `Struct`/`Enum` 字面量——它需要一个变量引用。
 
 Import 策略：
+
 - 同 namespace → `ImportInfo::SameFile`
 - 跨 namespace → `ImportInfo::NsReferDef`
 
 ### 修改的文件
 
-| 文件 | 变更 |
-|---|---|
-| `src/calcit/type_annotation.rs` | `resolve_to_enum_with_ref()`, `resolve_enum_from_program()` |
-| `src/runner/preprocess.rs` | `try_rewrite_tuple_args_to_enum_tuples()`, `try_rewrite_single_tuple_to_enum_tuple()`，集成到 Fn 分支 |
-| `docs/features/enums.md` | 新增 "Automatic Tuple-to-Enum Rewrite" 章节 |
-| `docs/features/records.md` | "Automatic Map-to-Record Rewrite" 章节（已有） |
-| `calcit/test-enum.cirru` | 新增 `test-tuple-to-enum` 测试 |
+| 文件                            | 变更                                                                                                  |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `src/calcit/type_annotation.rs` | `resolve_to_enum_with_ref()`, `resolve_enum_from_program()`                                           |
+| `src/runner/preprocess.rs`      | `try_rewrite_tuple_args_to_enum_tuples()`, `try_rewrite_single_tuple_to_enum_tuple()`，集成到 Fn 分支 |
+| `docs/features/enums.md`        | 新增 "Automatic Tuple-to-Enum Rewrite" 章节                                                           |
+| `docs/features/records.md`      | "Automatic Map-to-Record Rewrite" 章节（已有）                                                        |
+| `calcit/test-enum.cirru`        | 新增 `test-tuple-to-enum` 测试                                                                        |
 
 ## 5. 测试覆盖
 

package/rfc/04-16-wasm-data-structures.md

@@ -4,10 +4,32 @@
 
 现有 WASM codegen（`emit_wasm.rs`）采用 all-f64 策略，仅支持纯数值函数。本文档描述如何在保持 all-f64 ABI 兼容的前提下，增量引入 Tag、Record、Tuple/Enum 等结构化数据的支持。
 
+## 三层类型架构（核心设计原则）
+
+Calcit WASM codegen 按 **Rust `T` vs `dyn Trait`** 的思路分三层处理，详细设计见
+`recollect/WASM-ROADMAP.md §"类型化 WASM 架构：Rust 风格设计模型"`，这里摘要关键决策：
+
+| 层级            | Calcit 形态                                                                | WASM 表示                                                               | 阶段                  |
+| --------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| **静态**        | `Number`, `Bool`, `Tag`, `defstruct` Record, Enum Tuple                    | 直接 f64 / 线性内存 struct，零装箱                                      | S0（已完成）          |
+| **泛型单态化**  | `List<Number>`, `Map<Tag, Record>` 等带类型参数的集合；HOF lambda 类型已知 | 编译期展开专用函数；HOF 拦截器内联                                      | S0 HOF 路径（已完成） |
+| **动态（dyn）** | 标注 `:dynamic` 或无法推断的值；函数作为一等值                             | 装箱 tagged pointer（HEAP_MAGIC + type_tag + payload），运行时 dispatch | S1/S2（待做）         |
+
+**实现规则**：
+
+- 函数所有参数/返回值类型静态已知 → 走静态路径，零开销。
+- 类型参数已知的 HOF（`map`/`filter`/`foldl`）→ 编译期单态化，HOF 拦截器内联展开。
+- 类型未知（`:dynamic`）→ 装箱为 tagged pointer，运行时读 type_tag 分支 dispatch。
+- `assert-type` / downcast → 从 dyn 路径收窄回静态路径（读 tag → 失败则 `unreachable` → 成功则拆箱取 payload）。
+- 函数作为值（闭包）→ S1：函数表 `call_indirect`；S3：静态 lift + 捕获环境 struct。
+
+**给代码补类型标注就是在给 WASM 加速**——类型覆盖率直接决定静态路径覆盖率。
+实现 trait impl 系统时同样遵循此原则：trait 方法有具体类型时单态化，无类型时走 dyn dispatch。
+
 ## 设计决策（继承自初始实现）
 
 1. **二进制 `.wasm` 输出** — 使用 `wasm-encoder` crate 直接生成标准 WASM 二进制格式。
-2. **All-f64 类型策略** — 所有值统一为 f64，Bool 用 1.0/0.0 表示。
+2. **All-f64 类型策略** — 所有值统一为 f64，Bool 用 1.0/0.0 表示（静态层）；动态层用 i32 装箱指针（暂以 f64 编码传递）。
 3. **比较运算的 f64 返回** — 使用 `select` 指令将 i32 条件转为 f64 (1.0/0.0)。
 4. **recur 映射到 WASM loop** — 通过 `block_depth` 追踪嵌套深度。
 
@@ -17,22 +39,24 @@
 
 保持所有函数参数和返回值为 f64，扩展值的语义：
 
-| 值类型 | f64 表示方式 | 说明 |
-|--------|-------------|------|
-| Number | 直接 f64 | 不变 |
-| Bool | 1.0 / 0.0 | 不变 |
-| Nil | 0.0 | 不变 |
-| Tag | 正整数 f64 (1.0, 2.0, ...) | 编译时分配，全局唯一 |
-| Record 指针 | f64 编码的 i32 偏移 | 指向线性内存中的 Record 数据 |
-| Tuple 指针 | f64 编码的 i32 偏移 | 指向线性内存中的 Tuple 数据 |
+| 值类型      | f64 表示方式               | 说明                         |
+| ----------- | -------------------------- | ---------------------------- |
+| Number      | 直接 f64                   | 不变                         |
+| Bool        | 1.0 / 0.0                  | 不变                         |
+| Nil         | 0.0                        | 不变                         |
+| Tag         | 正整数 f64 (1.0, 2.0, ...) | 编译时分配，全局唯一         |
+| Record 指针 | f64 编码的 i32 偏移        | 指向线性内存中的 Record 数据 |
+| Tuple 指针  | f64 编码的 i32 偏移        | 指向线性内存中的 Tuple 数据  |
 
 指针与数值之间的转换：
+
 - 写入: `i32` → `f64.convert_i32_u`
 - 读取: `f64` → `i32.trunc_f64_u`
 
 ### 歧义规避
 
 Tag、指针、数值共用 f64 空间，依赖**编译时类型信息**区分：
+
 - WASM 子集要求 Record/Tuple 相关函数必须有类型标注
 - Tag 值与数值范围不重叠（Tag 从高位整数开始分配，或使用特殊编码）
 - 实验阶段不做运行时类型检查，类型错误由 Calcit 预处理保证
@@ -76,13 +100,13 @@ offset + 8*(n): field_{n-1} (f64, 8 bytes)
 
 ### 操作映射
 
-| Calcit 操作 | WASM 实现 |
-|-------------|----------|
-| `&%{} struct field1 val1 ...` | bump alloc + f64.store 每个字段 |
-| `&record:get record :field` | `f64.load (ptr + field_offset)` |
-| `&record:nth record idx tag` | `f64.load (ptr + (1 + idx) * 8)` |
-| `&record:assoc record :field val` | 复制整个 Record + 修改指定字段 |
-| `:field record` (tag-as-fn) | 等同于 `&record:get` |
+| Calcit 操作                       | WASM 实现                        |
+| --------------------------------- | -------------------------------- |
+| `&%{} struct field1 val1 ...`     | bump alloc + f64.store 每个字段  |
+| `&record:get record :field`       | `f64.load (ptr + field_offset)`  |
+| `&record:nth record idx tag`      | `f64.load (ptr + (1 + idx) * 8)` |
+| `&record:assoc record :field val` | 复制整个 Record + 修改指定字段   |
+| `:field record` (tag-as-fn)       | 等同于 `&record:get`             |
 
 ### 内存分配
 
@@ -117,11 +141,11 @@ offset + 16: payload_1 (f64, 8 bytes)
 
 ### 操作映射
 
-| Calcit 操作 | WASM 实现 |
-|-------------|----------|
-| `:: tag val1 val2 ...` | bump alloc + store tag + payloads |
-| `&tuple:nth tuple idx` | `f64.load (ptr + (1 + idx) * 8)` |
-| `tag-match` | load tag → if/else chain（小量 variants）或 `br_table`（多 variants） |
+| Calcit 操作            | WASM 实现                                                             |
+| ---------------------- | --------------------------------------------------------------------- |
+| `:: tag val1 val2 ...` | bump alloc + store tag + payloads                                     |
+| `&tuple:nth tuple idx` | `f64.load (ptr + (1 + idx) * 8)`                                      |
+| `tag-match`            | load tag → if/else chain（小量 variants）或 `br_table`（多 variants） |
 
 ### tag-match 编译
 
@@ -150,15 +174,16 @@ List 在 Calcit 中是持久化数据结构（`Vector(Vec)` 或 `TernaryTreeList
 
 ### 方案对比
 
-| 方案 | 复杂度 | 适用性 |
-|------|--------|--------|
-| Host import (JS 侧处理) | 低 | 适合 JS 互操作场景 |
-| 线性内存 UTF-8 | 中 | 需要自己维护 string pool |
-| WASM GC string (proposal) | 低 | 需要运行时支持 (V8/Deno ✅) |
+| 方案                      | 复杂度 | 适用性                      |
+| ------------------------- | ------ | --------------------------- |
+| Host import (JS 侧处理)   | 低     | 适合 JS 互操作场景          |
+| 线性内存 UTF-8            | 中     | 需要自己维护 string pool    |
+| WASM GC string (proposal) | 低     | 需要运行时支持 (V8/Deno ✅) |
 
 ### 结论
 
 本轮不实现 String。推荐路径：
+
 1. **近期**: host import 方案（`println` 等通过 host function 代理）
 2. **远期**: WASM GC string 标准化后直接采用
 

package/ts-src/calcit.procs.mts

@@ -43,6 +43,7 @@ export * from "./custom-formatter.mjs";
 export * from "./js-cirru.mjs";
 export * from "./js-arity-helpers.mjs";
 export * from "./js-tag-helpers.mjs";
+export * from "./js-buf-list.mjs";
 export { _$n_compare } from "./js-primes.mjs";
 
 import { CalcitList, CalcitSliceList, foldl } from "./js-list.mjs";
@@ -331,49 +332,7 @@ export function _$n_record_$o_nth(x: CalcitValue, idx: CalcitValue): CalcitValue
   return x.values[i];
 }
 
-// === BufList — mutable append-only list ===
-// Wrapper around a plain JS Array for O(1) push.
-export class CalcitBufList {
-  buf: CalcitValue[];
-  constructor(buf?: CalcitValue[]) {
-    this.buf = buf ?? [];
-  }
-}
-
-export function _$n_buf_list_$o_new(): CalcitBufList {
-  return new CalcitBufList();
-}
-
-export function _$n_buf_list_$o_push(buf: CalcitValue, item: CalcitValue): CalcitBufList {
-  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:push expected a buf-list, got ${buf}`);
-  buf.buf.push(item);
-  return buf;
-}
-
-export function _$n_buf_list_$o_concat(buf: CalcitValue, xs: CalcitValue): CalcitBufList {
-  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:concat expected a buf-list, got ${buf}`);
-  if (xs instanceof CalcitSliceList || xs instanceof CalcitList) {
-    const gen = xs.items();
-    let next = gen.next();
-    while (!next.done) {
-      buf.buf.push(next.value);
-      next = gen.next();
-    }
-  } else {
-    throw new Error(`&buf-list:concat expected a list, got ${xs}`);
-  }
-  return buf;
-}
-
-export function _$n_buf_list_$o_to_list(buf: CalcitValue): CalcitSliceList {
-  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:to-list expected a buf-list, got ${buf}`);
-  return new CalcitSliceList([...buf.buf]);
-}
 
-export function _$n_buf_list_$o_count(buf: CalcitValue): number {
-  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:count expected a buf-list, got ${buf}`);
-  return buf.buf.length;
-}
 export function _$n_set_$o_count(x: CalcitValue): number {
   if (x instanceof CalcitSet) return x.len();
 
@@ -2116,6 +2075,40 @@ export let _$n_map_$o_common_keys = (a: CalcitValue, b: CalcitValue): CalcitSet
   }
 };
 
+/** Single-pass diff: returns [drop-keys, new-diff, common-triples] in two traversals instead of 3+ */
+export let _$n_map_$o_diff_triple = (a: CalcitValue, b: CalcitValue): CalcitSliceList => {
+  if ((a instanceof CalcitMap || a instanceof CalcitSliceMap) && (b instanceof CalcitMap || b instanceof CalcitSliceMap)) {
+    let dropKeys: CalcitValue[] = [];
+    let commonTriples: CalcitValue[] = [];
+
+    // One pass over a: split into drop-keys and common-triples
+    let aKeys = a.keysArray();
+    for (let i = 0; i < aKeys.length; i++) {
+      let k = aKeys[i];
+      if (b.contains(k)) {
+        commonTriples.push(new CalcitSliceList([k, a.get(k), b.get(k)]));
+      } else {
+        dropKeys.push(k);
+      }
+    }
+
+    // One pass over b: collect entries not in a
+    let newDiffPairs: CalcitValue[] = [];
+    let bKeys = b.keysArray();
+    for (let i = 0; i < bKeys.length; i++) {
+      let k = bKeys[i];
+      if (!a.contains(k)) {
+        newDiffPairs.push(k);
+        newDiffPairs.push(b.get(k));
+      }
+    }
+
+    return new CalcitSliceList([new CalcitSet(dropKeys), new CalcitSliceMap(newDiffPairs), new CalcitSliceList(commonTriples)]);
+  } else {
+    throw new Error("&map:diff-triple expected 2 maps");
+  }
+};
+
 export let bit_shr = (base: number, step: number): number => {
   return base >> step;
 };

package/ts-src/js-buf-list.mts

@@ -0,0 +1,47 @@
+import { CalcitValue } from "./js-primes.mjs";
+import { CalcitList, CalcitSliceList } from "./js-list.mjs";
+
+// === CalcitBufList — mutable append-only list ===
+// Wrapper around a plain JS Array for O(1) push.
+// Use &buf-list:new / &buf-list:push / &buf-list:to-list in Calcit code.
+export class CalcitBufList {
+  buf: CalcitValue[];
+  constructor(buf?: CalcitValue[]) {
+    this.buf = buf ?? [];
+  }
+}
+
+export function _$n_buf_list_$o_new(): CalcitBufList {
+  return new CalcitBufList();
+}
+
+export function _$n_buf_list_$o_push(buf: CalcitValue, item: CalcitValue): CalcitBufList {
+  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:push expected a buf-list, got ${buf}`);
+  buf.buf.push(item);
+  return buf;
+}
+
+export function _$n_buf_list_$o_concat(buf: CalcitValue, xs: CalcitValue): CalcitBufList {
+  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:concat expected a buf-list, got ${buf}`);
+  if (xs instanceof CalcitSliceList || xs instanceof CalcitList) {
+    const gen = xs.items();
+    let next = gen.next();
+    while (!next.done) {
+      buf.buf.push(next.value);
+      next = gen.next();
+    }
+  } else {
+    throw new Error(`&buf-list:concat expected a list, got ${xs}`);
+  }
+  return buf;
+}
+
+export function _$n_buf_list_$o_to_list(buf: CalcitValue): CalcitSliceList {
+  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:to-list expected a buf-list, got ${buf}`);
+  return new CalcitSliceList([...buf.buf]);
+}
+
+export function _$n_buf_list_$o_count(buf: CalcitValue): number {
+  if (!(buf instanceof CalcitBufList)) throw new Error(`&buf-list:count expected a buf-list, got ${buf}`);
+  return buf.buf.length;
+}