@calcit/procs 0.12.20 → 0.12.23

package/README.md

@@ -29,12 +29,19 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 cargo install calcit
 ```
 
-3 binaries are installed:
+4 binaries are installed:
 
 - `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
 
+When installing from source, explicitly include both runners:
+
+```bash
+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
@@ -163,6 +170,8 @@ cargo run --bin cr -- calcit/test.cirru -1 js && yarn try-js
 cargo run --bin cr -- eval 'range 100'
 
 cr compact.cirru -1 ir # compiles intermediate representation into program-ir.cirru
+
+cr-wasm calcit/test-wasm.cirru # compile standalone wasm target to js-out/program.wasm
 ```
 
 - [Cirru Parser](https://github.com/Cirru/parser.rs) for indentation-based syntax parsing.

package/editing-history/202604170520-simplify-generic-defns-via-method-dispatch.md

@@ -0,0 +1,49 @@
+# Simplify generic core defns via `.method` dispatch
+
+## 概要
+
+将 `calcit-core.cirru` 中的泛型 defn（`assoc` / `contains?` / `count` / `empty` / `empty?` / `filter` / `first` / `get` / `includes?` / `nth` / `rest` / `map`）从多分支 `if (list? x) ... if (map? x) ... if (record? x) ...` 链简化为 `list?` 快速路径 + `.method` 动态分发。
+
+## 动机
+
+- 用户要求：优先使用 `.method` 这套已有概念承担多态分发，避免每新增类型（record / tuple / set 等）都要在每个 defn 中追加分支。
+- 所有 built-in 类型已在 `&core-*-methods` 中注册了对应的 `.assoc` `.count` `.empty?` `.get` `.nth` 等方法条目，编译期 `try_inline_method_call` 已能在静态类型已知时把方法调用内联为直接 proc 调用，runtime 则由 `invoke_method` 处理。这使得 defn 自身不再需要枚举类型。
+
+## 实现
+
+以 `empty?` 为例：
+
+```cirru
+defn empty? (x)
+  if (nil? x) true $ if (list? x) (&list:empty? x) (.empty? x)
+```
+
+保留 `nil?` 与 `list?` 两个前置分支，其余类型全部交给 `.empty?`。
+
+**为什么保留 `list?` 快速路径**：
+`ensure_ns_def_compiled(CORE_NS, &init-builtin-impls!)` 在预处理期会展开 `do` 等 macro，其中 `(empty? body)` 会在 impls 还未注册到 runtime 时被调用；若此时 `empty?` 体里就走 `.empty?` → `invoke_method` → `evaluate_symbol_from_program("&core-list-impls", ...)` 会命中 quick-path 失败（循环依赖），导致 panic：
+
+```
+preprocess builtin impls: CalcitErr { kind: Var, msg: "expected symbol `&core-list-impls` from path `calcit.core`, this is a quick path, should succeed", ... }
+```
+
+`list?` 本身只用 `(&= (type-of x) :list)` 等 proc，不依赖 impl 注册，能在 bootstrap 期安全使用，打破循环；其余类型的 methods 此时已构建完毕，可顺利走方法派发。
+
+## 波及范围
+
+- `src/cirru/calcit-core.cirru`：12 个 defn 的 body 瘦身。
+- 预处理期的 `try_specialize_polymorphic_call`（已有）照常将 `(assoc x k v)` 等静态可推断调用折叠为 `&list:assoc`/`&map:assoc` 等 proc。
+- runtime 侧未变：仍由 `invoke_method` + `&core-*-impls` 完成最终派发。
+
+## 验证
+
+- `cargo fmt`
+- `cargo clippy --release -- -D warnings`
+- `cargo test --release`：179 + 67 通过
+- `yarn check-all`：全部 WASM/JS/解释执行测试通过
+- recollect (`cr --entry test` + `cr --entry test js` + `node test.mjs`) ✓
+- respo (`cr --check-only` + `cr js` + `yarn vite build`) ✓
+
+## 备注
+
+- 下一步可以考虑：把那些只剩 `list?` 单分支的 defn 再收拢到一个运行时 primitive，或在 preprocess 阶段对 macro 展开期调用的 `empty?` 等函数强制内联 proc，从而彻底去掉这条 fast path。

package/editing-history/202604172316-wasm-do-println-fixes.md

@@ -0,0 +1,41 @@
+# 202604172316 — WASM `do` body 与 println host import 修复
+
+## 修复内容
+
+### 1. `do` 在 defn body 中的 WASM 编译问题
+
+**现象**：`defn test-println () do (println 42) 1` 编译后生成 `f64.const 0`（函数体为空）。
+
+**根因**：Cirru 语法中 `defn f () do expr1 expr2` 解析为 `(defn f () do expr1 expr2)`，body 数组为 `[do, expr1, expr2]` 三个独立元素（不是 `[(do expr1 expr2)]`）。`do` 作为裸 Import 节点出现在 `emit_expr` 时，触发 "unsupported WASM expression" 错误，导致函数被跳过并 fallback 为 `f64.const 0`。
+
+**修复**：在 `emit_expr` 中为 `Calcit::Import { def: "do" }` 添加特例，将其视为 no-op（emit 0.0 后由 `emit_body` 的 Drop 消耗掉）。
+
+```rust
+// `do` as bare body expression is a no-op sequencer
+Calcit::Import(import) if import.def.as_ref() == "do" => {
+  ctx.emit(f64_const(0.0));
+}
+```
+
+### 2. io.log_value host import（WASM println）
+
+- WASM codegen 对 `println`/`eprintln`/`echo` 调用 host import `io.log_value`。
+- `test-wasm.mjs` 提供 `io.log_value` 实现：读取堆内存判断类型，字符串解码 UTF-8，数字直接输出。
+- 添加 `test-println` 测试用例验证功能。
+
+### 3. TypeScript 运行时 BufList 修复
+
+`_$n_buf_list_$o_concat` 中 `CalcitSliceList` 的 `items` 是方法而非属性，需调用 `xs.items()` 并手动迭代 Generator（TS 配置不支持 `for...of` Generator）。
+
+## 受影响文件
+
+- `src/codegen/emit_wasm.rs`：`emit_expr` 新增 `do` no-op 特例；`emit_call_expr` Import 分支也保留 `do` 处理（用于 `(do ...)` 调用形式）
+- `ts-src/calcit.procs.mts`：修正 `_$n_buf_list_$o_concat` 迭代逻辑
+- `calcit/test-wasm.cirru`：新增 `test-println`
+- `scripts/test-wasm.mjs`：新增 `io.log_value` 实现与 `test-println` 断言
+
+## 关键经验
+
+- `do` 在 Calcit defn body 中是语法糖/占位符，预处理后展开为多个独立 body 表达式，不是 `(do ...)` 调用形式。WASM codegen 需将其视为 no-op。
+- WASM 编译错误时 fallback 为 `f64.const 0`（静默），调试时需检查 stderr 中的 `[wasm] skipping` 日志。
+- TS 的 Generator 不能直接 `for...of`，需手动调用 `.next()`。

package/editing-history/202604181208-split-emit-wasm-and-bump-version.md

@@ -0,0 +1,15 @@
+## Summary
+
+- Split the WASM code generator so `src/codegen/emit_wasm.rs` keeps orchestration while runtime helpers, method dispatch, and record/tuple emitters live in dedicated submodules.
+- Bumped the Calcit patch version from `0.12.20` to `0.12.21` for the next release.
+
+## Module Layout
+
+- `src/codegen/emit_wasm/runtime.rs` now owns host import definitions, module assembly, and internal runtime helper builders.
+- `src/codegen/emit_wasm/methods.rs` now owns dynamic method dispatch and rest-arg call argument packing.
+- `src/codegen/emit_wasm/records.rs` now owns record and tuple emission helpers.
+
+## Notes
+
+- The split is intended to be behavior-preserving; no WASM semantics were changed as part of this refactor.
+- Version strings were updated in `Cargo.toml`, `package.json`, and `lib/package.json`, while generated JS version text will be refreshed by the validation build.

package/editing-history/202604181430-wasm-list-match-and-method-dispatch.md

@@ -0,0 +1,5 @@
+- WASM export names now stay unique by qualifying only colliding defs with `ns/def`.
+- `list-match` macro now uses `&list:empty?` after the existing list guard, avoiding the unsupported generic `empty?` invoke path in WASM.
+- Added minimal `Calcit::Method` handling in WASM for dynamic `.empty?`, `.count`, `.nth`, and `.get` calls.
+- `&tuple:nth` in WASM now accepts dynamic indices instead of literal-only indices.
+- Verified `yarn try-all` still passes in calcit after the WASM changes.

package/editing-history/202604182041-cr-wasm-split-and-runtime-stability.md

@@ -0,0 +1,18 @@
+# 2026-04-18 20:41 CR WASM Split and Runtime Stability
+
+## 关键修改
+
+- 将 `cr wasm` 拆分为独立二进制 `cr-wasm`，避免主 `cr` 命令体积和职责继续膨胀。
+- `calcit` 的 WASM 相关验证脚本和 CI 调整为优先走 `cr-wasm`。
+- 修复 `emit_wasm` 中 map/set/tuple 相关回归点，恢复 `yarn check-all` 的可通过性。
+- 修复 `recollect` 在 Rust 运行时下的 `patch-map` 路径，避免本地变量解析异常导致测试阻断。
+- 将 `recollect` 的 wasm 测试分为核心 smoke（阻断）与扩展 probes（非阻断），保证 wasm 独立验证但不影响 rust/js 主链路。
+- 版本提升到 patch：`0.12.22`。
+
+## 经验与注意事项
+
+- 对 `compact.cirru` 的修改必须通过 `cr edit`/`cr tree` 完成，避免文本直接编辑破坏结构。
+- 在多项目联动（calcit + recollect）场景下，发布前验证至少应覆盖：
+  - calcit: `yarn check-all`
+  - recollect: `yarn test:cr`、`yarn test:js`、`yarn test:wasm`
+- macOS 上遇到 `iconv` 链接问题时，需带 `SDKROOT` 执行构建命令进行最终回归确认。

package/editing-history/202604182045-v0.12.23-ci-wasm-fix.md

@@ -0,0 +1,13 @@
+# 2026-04-18 20:45 v0.12.23 CI WASM Fix
+
+## 变更摘要
+
+- 解决 GitHub Actions `try wasm` 步骤失败（exit 127）的问题。
+- 原因：workflow 直接调用 `./target/debug/cr-wasm`，但未提前构建二进制。
+- 修复：在 `.github/workflows/test.yaml` 的 wasm 步骤中先执行 `cargo build --bin cr-wasm`，再运行 `scripts/test-wasm.sh`。
+- 版本升级：`0.12.22` -> `0.12.23`（`Cargo.toml` 与 `package.json` 同步）。
+
+## 验证
+
+- 本地 `cargo check` 通过。
+- 后续以推送后的 Actions `Test` 工作流成功作为发布门禁，再创建 GitHub Release。

package/lib/calcit.procs.mjs

@@ -283,6 +283,56 @@ export function _$n_record_$o_count(x) {
         return x.fields.length;
     throw new Error(`expected a record ${x}`);
 }
+export function _$n_record_$o_field_tag(x, idx) {
+    if (!(x instanceof CalcitRecord))
+        throw new Error(`&record:field-tag expected a record, got ${x}`);
+    const i = idx;
+    if (i < 0 || i >= x.fields.length)
+        throw new Error(`&record:field-tag index ${i} out of bounds (${x.fields.length})`);
+    return x.fields[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();
@@ -1387,6 +1437,9 @@ export let nil_$q_ = (x) => {
 export let tag_$q_ = (x) => {
     return x instanceof CalcitTag;
 };
+export let symbol_$q_ = (x) => {
+    return x instanceof CalcitSymbol;
+};
 export let map_$q_ = (x) => {
     return x instanceof CalcitSliceMap || x instanceof CalcitMap;
 };

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.20",
+    "version": "0.12.23",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",
@@ -19,6 +19,7 @@
         "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",
+        "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",
         "try-js-brk": "cargo run --bin cr -- calcit/test.cirru js && node --inspect-brk js-out/main.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.20",
+  "version": "0.12.23",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",
@@ -19,6 +19,7 @@
     "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",
+    "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",
     "try-js-brk": "cargo run --bin cr -- calcit/test.cirru js && node --inspect-brk js-out/main.mjs",

package/rfc/04-15-wasm-compilation-feasibility.md

@@ -222,6 +222,58 @@ WASM GC proposal（2024 年起 V8/SpiderMonkey 已发布）提供：
 2. **中期**: 路径二的子集 — 从纯数值计算函数开始，生成 WASM 模块作为 JS codegen 的"加速岛"（hot island），由 JS 运行时按需调用
 3. **远期**: 路径三 — 随 WASM GC 工具链成熟，逐步扩展可编译子集
 
+## 2026-04 进展状态
+
+当前项目已经不再停留在“可行性评估”阶段，而是进入“持续补齐子集能力”的实施阶段：
+
+- `src/codegen/emit_wasm.rs` 已落地，并拆分出 `runtime.rs`、`methods.rs`、`records.rs` 子模块维护。
+- `yarn check-all` 已纳入 WASM 验证，当前会编译 `calcit/test-wasm.cirru` 并通过 `scripts/test-wasm.mjs` 做 Node.js 侧断言。
+- 发布版本 `0.12.21` 已覆盖 BufList、基础 map/set/list/tuple/record 操作、若干动态方法分派、host println/logging 等运行时能力。
+- `recollect` 已可在已发布的 `setup-cr` 工具链上启用 WASM 回归测试，但仍有更高层 API 与应用侧依赖未覆盖。
+
+可以更直白地估计当前距离：
+
+- 距离“底层运行时对子集集合操作足够稳固”大约还剩 `30%`。
+- 距离“`calcit.core` 高频 helper 在真实下游项目里不需要大面积绕开”大约还剩 `50%`。
+- 距离“Respo/recollect 这类应用侧流程可稳定跑通”大约还剩 `75%`。
+
+这意味着近期重点不再是“证明能不能做”，而是“持续缩小尚未支持的语言与运行时边界”。
+
+## 近期计划细化
+
+### P0: 消除被下游真实项目阻塞的运行时缺口
+
+优先级依据不是抽象完整性，而是下游项目是否真实卡住：
+
+1. 继续补动态 method/runtime 缺口。
+  - `.contains?`、`.includes?`、`.empty` 已开始在 direct method path 上落地，但 `calcit.core` wrapper 侧仍有 skip 项，需要继续把 lowering 对齐到底。
+  - 当前仍缺 `.min`、`.max` 等集合方法的稳定支持。
+  - 这些能力会直接影响 `calcit.core` 高层 helper 在 WASM 下的可用性。
+
+2. 继续补充 `calcit.core` 常见高阶路径。
+  - `foldl`、`foldl-shortcut`、`foldr-shortcut`、`sort`、`&call-spread` 仍是大量跳过项的源头。
+  - 这部分不是为了追求“理论完备”，而是为了减少真实项目中被迫绕开 core helper 的情况。
+
+3. 持续扩大 `test-wasm.cirru` 的下游回归覆盖。
+  - 每补一个能力，都应优先加一个最小但能锁定语义边界的 WASM 用例。
+  - 需要优先覆盖下游真实依赖的模式，而不是只补纯数值 demo。
+
+### P1: 以 recollect 为代表补 API 级验证
+
+`recollect` 已经证明当前 WASM 子集可支撑一部分 diff/patch 逻辑，因此下一阶段应显式面向下游 API：
+
+1. 用 API parity fixtures 覆盖 `diff-twig` / `patch-twig`。
+2. 增加 record-heavy / map-heavy / nested tree 场景。
+3. 把“当前可运行”和“仍 blocked”的场景分开记录，避免 roadmap 只剩模糊叙述。
+
+### P2: 推进解释器到 wasm32 的基础编译检查
+
+路径一仍值得保留，但它的短期目标应更具体：
+
+1. 先跑通 `cargo build --target wasm32-unknown-unknown --lib`。
+2. 把剩余链接错误收敛成明确的 `cfg` 门控清单。
+3. 把解释器路径与 AOT 路径共享的可复用运行时能力整理出来，避免两条线重复补洞。
+
 ## 验证第一步
 
 ```bash

package/ts-src/calcit.procs.mts

@@ -316,6 +316,57 @@ export function _$n_record_$o_count(x: CalcitValue): number {
 
   throw new Error(`expected a record ${x}`);
 }
+
+export function _$n_record_$o_field_tag(x: CalcitValue, idx: CalcitValue): CalcitTag {
+  if (!(x instanceof CalcitRecord)) throw new Error(`&record:field-tag expected a record, got ${x}`);
+  const i = idx as number;
+  if (i < 0 || i >= x.fields.length) throw new Error(`&record:field-tag index ${i} out of bounds (${x.fields.length})`);
+  return x.fields[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();
 
@@ -1504,6 +1555,9 @@ export let nil_$q_ = (x: CalcitValue): boolean => {
 export let tag_$q_ = (x: CalcitValue): boolean => {
   return x instanceof CalcitTag;
 };
+export let symbol_$q_ = (x: CalcitValue): boolean => {
+  return x instanceof CalcitSymbol;
+};
 export let map_$q_ = (x: CalcitValue): boolean => {
   return x instanceof CalcitSliceMap || x instanceof CalcitMap;
 };