@calcit/procs 0.12.18 → 0.12.20

package/rfc/04-15-match-syntax-rfc.md

@@ -0,0 +1,175 @@
+# RFC: Native `match` Syntax with Exhaustiveness Checking
+
+状态：Implemented
+日期：2026-04-15
+
+---
+
+## 1. 概要
+
+引入新的原生语法 `match`，用于对 enum（tagged union）进行模式匹配。与现有 `tag-match` 宏不同，`match` 在预处理阶段执行穷尽性检查（exhaustiveness checking），在运行时直接执行分支匹配，在 JS 代码生成中输出高效的 if-else 链。
+
+## 2. 动机
+
+### 问题
+
+`tag-match` 是定义在 `calcit-core.cirru` 中的宏，展开后变成嵌套的 `if` + `identical?` 表达式。宏展开后：
+
+- **丢失结构信息**：预处理器只看到 `if`/`identical?`，无法知道"这是一个多分支枚举匹配"
+- **无法做穷尽性检查**：展开后的代码无法回溯到原始的分支列表
+- **无法校验变体存在性**：拼错 tag 名只会得到运行时错误
+- **无法校验 arity**：绑定数量与变体定义不匹配只会运行时报错
+
+### 解决方案
+
+将 `match` 作为原生语法（`CalcitSyntax::Match`），在编译器各阶段都能看到完整的分支结构：
+
+```
+源码 → 预处理（穷尽性+类型推断） → 运行时（直接分支匹配） → JS（if-else 链）
+```
+
+## 3. 语法设计
+
+### 基本形式
+
+```cirru
+match <value>
+  (<pattern1>) <body1>
+  (<pattern2> <binding1> <binding2>) <body2>
+  _ <default-body>
+```
+
+在 Cirru 的缩进规则下，每一行的 `pattern` 和 `body` 构成一个二元组 `(pattern body)`，自然映射为 AST 中的 pair。
+
+### Pattern 形式
+
+| Pattern            | 含义                       | 示例                       |
+| ------------------ | -------------------------- | -------------------------- |
+| `(:tag)`           | 零载荷变体                 | `(:ok) :success`           |
+| `(:tag b1 b2 ...)` | 带载荷变体，绑定到局部变量 | `(:err msg) (println msg)` |
+| `_`                | 通配符（匹配所有）         | `_ :default`               |
+
+### 完整示例
+
+```cirru
+defenum Result0 (:ok) (:err :string)
+
+let
+    r $ %:: Result0 :err |oops
+  match r
+    (:ok) :success
+    (:err msg) msg
+; => |oops
+```
+
+### 与 `tag-match` 的对比
+
+`match` 和 `tag-match` 的分支书写格式完全相同（都是 `(pattern body)` 对），迁移仅需将 `tag-match` 关键字替换为 `match`：
+
+```cirru
+; Before
+tag-match r
+  (:ok) :success
+  (:err msg) msg
+
+; After
+match r
+  (:ok) :success
+  (:err msg) msg
+```
+
+## 4. 预处理阶段
+
+### 类型推断
+
+通过 `infer_type_from_expr` 从值表达式推断枚举类型：
+
+1. 直接类型标注 → `CalcitTypeAnnotation::Tuple(enum_ref)` → 得到 `CalcitEnum`
+2. TypeSlot 引用 → 解析后得到 `CalcitTypeAnnotation::Enum(e, _)` → 得到 `CalcitEnum`
+3. 推断失败 → 跳过穷尽性检查（仍可在运行时匹配）
+
+### 变体校验
+
+对每个 `(:tag binding ...)` pattern：
+
+- 检查 `tag` 是否存在于枚举定义的 variants 中
+- 检查 binding 数量是否匹配 variant 的 `arity()`
+- 不匹配时产生 `[Warn]` 预处理警告
+
+### 穷尽性检查
+
+收集所有分支覆盖的 tag → 与枚举的全部 variant tag 做集合差：
+
+```
+missing = all_variants - covered_tags
+```
+
+若 `missing` 非空且无 `_` 通配符，产生警告：
+
+```
+[Warn] match on `Result0` is not exhaustive. Missing variant(s): [:ok]
+```
+
+### 绑定类型推断
+
+对 pattern 中的每个 binding symbol，从 `EnumVariant::payload_types()` 获取对应位置的类型标注，创建 `CalcitLocal` 并注入 body 的作用域类型表。
+
+## 5. 运行时行为
+
+`syntax_match` 的执行流程：
+
+1. 求值 `value` 表达式
+2. 解构为 `CalcitTuple { tag, extra, .. }`
+3. 遍历分支对 `(pattern body)`：
+   - 若 pattern 是 `_` → 匹配成功，求值 body 返回
+   - 若 pattern 是 `(:tag b1 b2 ...)` 且 tag 相等且 arity 匹配 → 创建作用域绑定 `b1=extra[0], b2=extra[1], ...`，求值 body 返回
+4. 所有分支都不匹配 → 运行时错误 `"match: no matching branch for tag :xxx"`
+
+## 6. JS 代码生成
+
+生成立即执行函数表达式（IIFE）：
+
+```javascript
+(() => {
+  let match_v = <value>;
+  let match_t = _$n_tuple_$o_nth(match_v, 0);
+  if (match_t === _kn_ok && _$n_tuple_$o_count(match_v) === 1) {
+    return kwd_$o_success;  // (:ok) :success
+  } else if (match_t === _kn_err && _$n_tuple_$o_count(match_v) === 2) {
+    let msg = _$n_tuple_$o_nth(match_v, 1);
+    return msg;  // (:err msg) msg
+  } else {
+    throw new Error("match: no matching branch for tag");
+  }
+})()
+```
+
+通配符 `_` 分支生成无条件 `else` 块。
+
+## 7. 实现文件
+
+| 文件                           | 变更                                               |
+| ------------------------------ | -------------------------------------------------- |
+| `src/calcit/syntax_name.rs`    | `CalcitSyntax::Match` 变体 + `SyntaxTypeSignature` |
+| `src/builtins/syntax.rs`       | `syntax_match()` 运行时处理器                      |
+| `src/builtins.rs`              | dispatch 入口                                      |
+| `src/runner/preprocess/mod.rs` | `preprocess_match()` 预处理+穷尽性检查             |
+| `src/codegen/emit_js.rs`       | `gen_match_code()` JS 代码生成                     |
+| `calcit/test-enum.cirru`       | 测试用例                                           |
+
+## 8. 迁移指南
+
+`tag-match` 和 `match` 的分支语法完全一致，迁移只需：
+
+1. 将 `tag-match` 替换为 `match`
+2. 确保被匹配的值有明确的枚举类型标注（以启用穷尽性检查）
+3. 根据编译器的穷尽性警告补充遗漏的分支或添加 `_` 通配符
+
+`tag-match` 仍然可用，不会被移除。
+
+## 9. 限制与未来工作
+
+- **当前**：类型推断依赖函数 schema 或显式 `%::` 构造，局部变量的枚举类型有时无法推断
+- **当前**：不支持嵌套 pattern（如 `(:ok (:inner x))`）
+- **未来**：可扩展为支持 struct/record 的解构匹配
+- **未来**：可添加 `match` 表达式的返回类型推断（从所有分支 body 计算 union type）

package/rfc/04-15-type-directed-optimization-catalog.md

@@ -0,0 +1,170 @@
+# 类型导向优化机会目录
+
+## 背景
+
+随着 `&record:nth` 的 O(1) 索引重写（commit `2fd2776` 及后续 JS field-tag 修复）落地，Calcit 预处理阶段已具备"在类型已知时改写 AST 以提升运行效率"的基础设施。本文档系统梳理各数据结构的现状与可做的同类优化，供后续逐项推进。
+
+## 数据结构现状
+
+| 类型   | 内部表示                                        | 查询复杂度                    | 更新复杂度          | 已有编译期优化                                                               |
+| ------ | ----------------------------------------------- | ----------------------------- | ------------------- | ---------------------------------------------------------------------------- |
+| Record | `Vec<Calcit>` + 字段按字母排序的 `CalcitStruct` | O(log n) 二分                 | O(n) clone Vec      | `&record:nth` 索引重写 ✅, `&record:assoc-at` ✅ P1, `&record:with-at` ✅ P2 |
+| Map    | `rpds::HashTrieMapSync`                         | O(1) hash                     | O(1) persistent     | 无                                                                           |
+| List   | `Vec` / `TernaryTreeList` 自动切换              | O(1) 或 O(log n)              | O(1) prepend/append | 结构自动选择                                                                 |
+| Tuple  | tag + `Vec<Calcit>`                             | O(1) index                    | O(n) clone          | enum variant HashMap 查找                                                    |
+| Set    | `rpds::HashTrieSetSync`                         | O(1) hash                     | O(1) persistent     | 无                                                                           |
+| Scope  | `Vec<ScopePair>`                                | O(n) 反向线性扫描（缓存友好）  | O(1) push           | ✅ P5 — 从 `TernaryTreeList` 改为 `Vec`                                      |
+
+## 优化项目
+
+### P0: Tag 调用 Record 的运行时 fallback ✅ `0116e54`
+
+**问题**: `(:field x)` 在 runner.rs 只处理 `Calcit::Map`。当 `x` 是 `Calcit::Record` 时直接报错 `"expected a hashmap"`。预处理阶段的 `(:tag record)` → `&record:nth` 重写仅在类型已知时生效；类型未知时走 fallback 触发运行时错误。
+
+**位置**: `src/runner.rs` L318-336，`Calcit::Tag(k)` 分支。
+
+**方案**: 在 Map 分支后增加 Record 处理：
+
+```rust
+} else if let Calcit::Record(record) = &v {
+    Ok(record.get(k.ref_str()).cloned().unwrap_or(Calcit::Nil))
+}
+```
+
+**性质**: 正确性修复，非纯性能优化。是渐进式类型策略的前提。
+
+**影响**: 高 — 允许 `(:field x)` 在类型未知时也能正确运行。
+
+---
+
+### P1: `&record:assoc` 编译期索引化 ✅ `44a8bfa`
+
+**问题**: `&record:assoc record :field value` 运行时做 `index_of` 二分查找定位字段，然后 clone 整个 `Vec<Calcit>` 再改一个位置。
+
+**位置**: `src/builtins/records.rs` L1020-1055。
+
+**方案**: 模式与 `&record:nth` 完全一致 — 预处理阶段类型已知时，算出字段索引，emit `NativeRecordAssocAt(record, idx, :tag, value)`：
+
+- 新增 `CalcitProc::NativeRecordAssocAt` variant
+- `proc_name.rs` 添加签名 `(record, number, tag, any)`
+- `records.rs` 添加 `record_assoc_at` 运行时函数（跳过 `index_of`，直接 `values[idx] = value`）
+- `emit_js.rs` 添加 codegen（JS 端同样省掉运行时字段查找）
+- `preprocess/mod.rs` 在检测到 `NativeRecordAssoc` + 已知类型时做重写
+
+**收益**: 每次 Record 字段更新省一次 O(log n) 二分查找。
+
+**影响**: 中高 — Record 更新在 Cumulo updater 和 Respo state 中是高频操作。
+
+---
+
+### P2: `&record:with` 批量更新索引化 ✅ `0e705f1`
+
+**问题**: `&record:with record :a 1 :b 2` 每个字段都做一次 `index_of` 二分查找。
+
+**位置**: `src/builtins/records.rs` L630-720。
+
+**方案**: 类型已知时，编译期预计算所有字段索引，emit 一个携带 `[(idx, value)]` 的批量更新指令。
+
+**收益**: k 个字段更新从 k×O(log n) 降到 O(k)。
+
+**影响**: 中 — 构造新 Record variant 或批量 state 更新时受益。
+
+---
+
+### P3: `tag-match` 分支整数化 ⬜ 推迟（侵入性大，CalcitTuple 12+ 构造点需改动）
+
+**问题**: `tag-match` 运行时用 tag 字符串逐一比较（线性扫描分支）。JS codegen 也是 if-else 链。
+
+**位置**: `src/builtins/syntax.rs` L933-1050（runner），`src/codegen/emit_js.rs` L897-978（JS codegen）。
+
+**方案**:
+
+- **Rust 端**: enum 类型已知时预处理阶段把 tag 比较替换为 `variant_index` 的整数比较
+- **JS 端**: emit `switch (tag.idx)` 替代 if-else 链
+
+**收益**: 5+ 分支时 O(n) → O(1)。
+
+**影响**: 中 — 状态机、消息路由场景（Cumulo updater dispatcher）明显加速。
+
+---
+
+### P4: Method dispatch 静态绑定 ⬜ 推迟（复杂度高，待类型覆盖率提高）
+
+**问题**: `.method obj` 运行时路径：① 匹配 receiver 类型 → ② 查 impl 列表（builtin 还要 evaluate symbol）→ ③ 线性遍历 `impls` 数组找方法名。
+
+**位置**: `src/builtins/meta.rs` L1016-1095，`method_call_impls` 函数。
+
+**方案**: 预处理阶段 receiver 类型和 trait 均已知时，直接解析到 `CalcitFn`/`CalcitProc`，把 `.method obj args` 重写为 `(resolved-fn obj args)`。
+
+**收益**: 消除 symbol resolution + linear impl search。
+
+**影响**: 中 — `.map`, `.filter`, `.show` 等核心 API 全部走 method dispatch。
+
+---
+
+### P5: Scope 变量查找优化 ✅ `07d6dfc`
+
+**问题**: `CalcitScope` 用 `TernaryTreeList<ScopePair>` 存变量，lookup 向后线性扫描 O(n)。每次变量引用（每个表达式节点）都付出这个代价。
+
+**位置**: `src/calcit/fns.rs`。
+
+**实际方案**: 采用 **Vec 方案** — 把 `CalcitScope` 内部从 `TernaryTreeList<ScopePair>` 改为 `Vec<ScopePair>`，`get()` 用 `.iter().rev()` 反向线性扫描。对于典型 2-3 变量的小 scope，Vec 的缓存局部性远优于 tree 结构。
+
+**注**: HashMap 方案实测有 ~1% 回退（hash 开销大于小 scope 的线性扫描），Vec 方案反而带来 ~13% fibo 基准提升。
+
+**收益**: fibo 基准从 ~836ms 降到 ~728ms（~13% 提升）。
+
+**影响**: 高 — 变量查找是最热操作，对解释器整体吞吐量有根本性影响。
+
+---
+
+### P6: `get-in` / `assoc-in` 静态路径展开
+
+**问题**: `get-in base [:a :b :c]` 是 Calcit 编写的递归函数（`calcit-core.cirru`），每层递归拆列表 + 动态 `get`。
+
+**方案**: 路径是字面量列表且 base 类型已知 Record 时，编译期展开为嵌套 `&record:nth`。`assoc-in` 同理展开为嵌套的 `&record:assoc-at`。
+
+**收益**: 消除递归、list 分解、运行时字段查找。
+
+**影响**: 中低 — 频率中等，但 Cumulo updater 中 `assoc-in db [:users user-id :field] value` 是核心模式。
+
+---
+
+### P7: `if` 条件常量折叠 ✅ `fa325c6`
+
+**问题**: `if true x y` 运行时仍求值条件。
+
+**方案**: 预处理阶段条件是字面量 `true`/`false`/`nil` 时直接消除分支。在 `preprocess_if()` 中，预处理完 cond/true/false 三个子表达式后，检查 `match &cond_form { Calcit::Bool(true) => return Ok(true_form), Calcit::Bool(false) | Calcit::Nil => return Ok(false_form), _ => {} }`。
+
+**影响**: 低 — 手写代码少见，但宏展开后常见。
+
+---
+
+## 实现模式参考
+
+所有 Record 相关优化遵循 `&record:nth` 已验证的模式：
+
+1. `proc_name.rs` — 新增 `CalcitProc` variant + `ProcTypeSignature`
+2. `records.rs` — 新增运行时函数（接受已解析的索引参数）
+3. `preprocess/mod.rs` — 检测原始 proc + 类型已知时重写 AST
+4. `emit_js.rs` — 添加 codegen 分支（JS 可能需要不同策略，参考 `&record:nth` 的 field-tag 方案）
+5. `type_checking.rs` / `type_inference.rs` — 确保新 proc 参与类型检查
+
+## 执行记录
+
+### 已完成（fibo 基准: 836ms → 718ms，总提升 ~14%）
+
+| 顺序 | 项目 | Commit    | 关键变更                                | 基准影响                           |
+| ---- | ---- | --------- | --------------------------------------- | ---------------------------------- |
+| 1    | P0   | `0116e54` | runner.rs Tag-call Record fallback      | 正确性修复                         |
+| 2    | P1   | `44a8bfa` | NativeRecordAssocAt + preprocess 重写   | Record 更新加速（fibo 不涉及）     |
+| 3    | P5   | `07d6dfc` | Scope 从 TernaryTreeList 改为 Vec       | ~13% fibo 提升（最大单项收益）     |
+| 4    | P2   | `0e705f1` | NativeRecordWithAt 批量索引化           | Record 批量更新加速（fibo 不涉及） |
+| 5    | P7   | `fa325c6` | if 常量折叠                             | 宏展开场景受益                     |
+| -    | 额外 | `7c04880` | runtime def resolution 去重复 RwLock 读 | 微优化                             |
+
+### 待定
+
+- **P3**: tag-match 整数化 — 推迟，CalcitTuple 12+ 构造点需改动，侵入性大
+- **P4**: Method dispatch 静态绑定 — 推迟，实现复杂度高
+- **P6**: get-in/assoc-in 静态路径展开 — 未开始，视实际瓶颈决定

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

@@ -0,0 +1,236 @@
+# WASM 编译可行性评估
+
+## 目标
+
+评估 Calcit 子集编译到 WASM 执行的可行性，分三个层面：
+
+1. **解释器本身编译为 WASM**（在浏览器中运行 Calcit 解释器）
+2. **Calcit 源码 AOT 编译到 WASM**（把 Calcit 程序直接翻译为 WASM 字节码）
+3. **利用 WASM GC proposal** 的远期路径
+
+## 依赖兼容性
+
+### 核心依赖（Library crate）
+
+| 依赖 | 用途 | WASM 兼容 | 说明 |
+|------|------|----------|------|
+| `rpds` 1.1 | Map/Set persistent DS | ✅ | 支持 `no_std`，纯 Rust |
+| `im_ternary_tree` 0.0.20 | CalcitList 后端 | ✅ | 纯 Rust，无平台依赖 |
+| `cirru_edn` | EDN 解析 | ✅ | 纯 Rust |
+| `cirru_parser` | Cirru 语法解析 | ✅ | 纯 Rust |
+| `rmp-serde` | MessagePack 序列化 | ✅ | 纯 Rust |
+
+### CLI-only 依赖（已有或需要 cfg 门控）
+
+| 依赖 | WASM | 现状 |
+|------|------|------|
+| `libloading` 0.9 | ❌ | 已 `cfg(not(wasm32))` 排除 |
+| `ctrlc` 3.4 | ❌ | 已 `cfg(not(wasm32))` 排除 |
+| `notify` 8.0 | ❌ | 仅 `src/bin/cr.rs` 使用，需新增门控 |
+| `walkdir` 2.5 | ❌ | 仅 CLI 路径扫描，需新增门控 |
+| `ureq` 3.2 | ⚠️ | 有 `wasm` feature 但需验证 |
+
+**结论**: 核心数据结构和运行时无阻塞性依赖。
+
+## 全局状态审计
+
+WASM 是单线程的，以下全局状态需要关注：
+
+### RwLock 包装（兼容，无需改动）
+
+- `PROGRAM_CODE_DATA` — `LazyLock<RwLock<ProgramCodeData>>`
+- `PROGRAM_RUNTIME_DATA_STATE` — `LazyLock<RwLock<ProgramRuntimeData>>`
+- `PROGRAM_COMPILED_DATA_STATE` — `LazyLock<RwLock<ProgramCompiledData>>`
+- `PROGRAM_DEF_ID_INDEX` — `LazyLock<RwLock<ProgramDefIdIndex>>`
+
+WASM 单线程下 `RwLock` 退化为无竞争路径，开销极低。
+
+### thread_local!（需评估）
+
+| 位置 | 变量 | 影响 |
+|------|------|------|
+| `type_annotation.rs` | `TYPE_ANNOTATION_WARNING_CONTEXT` | WASM 下变全局，语义不变 |
+| `type_annotation.rs` | `TYPE_SLOTS` | 同上 |
+| `preprocess/mod.rs` | `PREPROCESS_COMPILE_GUARD` | 同上 |
+| `preprocess/mod.rs` | `EXPECTED_FN_TYPE` | 同上 |
+| `preprocess/mod.rs` | `EXPECTED_STRUCT_TYPE` | 同上 |
+| `emit_js.rs` | `INLINE_ALL_ARGS` | codegen 专用，WASM target 可能不需要 |
+
+**结论**: `thread_local!` 在 WASM 下退化为进程全局（因为只有一个线程），语义上没有破坏。不需要大规模重构，但如果追求整洁可改为显式参数传递（约 15 处）。
+
+### AtomicBool（兼容）
+
+- `CODEGEN_MODE`, `CODEGEN_SKIP_ARITY_CHECK` — 单线程下原子操作退化为普通读写。
+
+## 路径一：解释器编译为 WASM
+
+### 方案
+
+- 目标: `wasm32-unknown-unknown`
+- 仅编译 lib crate（排除 `src/bin/` 全部）
+- 通过 `wasm-bindgen` 或 `wasm-pack` 导出 API
+- 内嵌 `calcit-core.rmp` snapshot 作为 WASM 数据段（`include_bytes!` 天然支持）
+
+### 导出接口设计
+
+```rust
+#[wasm_bindgen]
+pub fn eval_calcit(code: &str) -> Result<String, String> {
+    // 1. 加载内嵌 core snapshot
+    // 2. 解析 code 为 Cirru
+    // 3. 预处理 + 执行
+    // 4. 返回序列化结果
+}
+```
+
+### 需要的改动
+
+1. 补充 `cfg` 门控：`notify`, `walkdir` 相关代码
+2. `Cargo.toml` 添加 `[lib]` crate-type 含 `cdylib`
+3. 添加 `wasm-bindgen` 可选依赖
+4. 处理 `std::fs::read_to_string` 等 IO 调用（lib 内应已无直接调用，需验证）
+
+### 工作量
+
+小 — 主要是补门控和写胶水代码。
+
+### 用途
+
+- 浏览器端 Calcit REPL / playground
+- 在线文档中的交互式代码示例
+- 嵌入到 VS Code WebView 中执行
+
+## 路径二：AOT 编译 Calcit 子集到 WASM
+
+### 子集定义
+
+能编译到 WASM 的 Calcit 特性：
+
+```
+✅ 可静态编译:
+  - defn / fn（纯函数）
+  - Record（defstruct / %{}）— 映射到线性内存 struct
+  - Enum + tag-match — 映射到整数 tag + switch
+  - Number / Bool / Tag — 映射到 WASM 原生类型
+  - let 绑定
+  - if / cond 条件
+  - recur（尾递归 → WASM loop）
+  - 算术运算（+, -, *, /, mod, 比较）
+
+⚠️ 需要 host runtime bridge:
+  - String 操作 — WASM 无原生字符串，需 host 分配
+  - persistent Map / Set — 需 GC 或 host call
+  - List 高阶操作（map / filter / foldl）— 回调需函数引用
+
+❌ 排除（留给解释器 / JS codegen）:
+  - 宏系统（编译期展开，不进入 WASM）
+  - eval / quasiquote（需完整解释器）
+  - 动态 method dispatch（无法静态解析）
+  - Atom / Ref（可变状态需 host 端管理）
+  - FFI / dylib 调用
+```
+
+### 编译策略
+
+```
+Calcit 源码
+  → 预处理（宏展开 + 类型推导 + 重写优化）
+  → IR（复用 gen_ir.rs 的 Cirru EDN IR）
+  → emit_wasm.rs（新模块，IR → WAT/WASM）
+  → .wasm 二进制
+```
+
+新增 `src/codegen/emit_wasm.rs` 与 `emit_js.rs` 并列：
+
+- 函数 → `(func $name (param ...) (result ...) ...)`
+- Record → 线性内存布局，字段按排序索引直接偏移
+- Tag → 整数常量（编译期分配）
+- tag-match → `br_table`（WASM 跳转表）
+- let → `local.set` / `local.get`
+- recur → `loop` + `br`
+
+### 类型要求
+
+**必须全局类型已知** — 这是 AOT 路径的硬前提：
+
+- 所有函数签名完整（schema 覆盖）
+- Record 字段类型确定（`CalcitStruct.field_types` 非 Dynamic）
+- Enum variant payload 类型确定
+
+当前类型系统已支持这些标注，但实际代码库覆盖率取决于用户代码。
+
+### 内存模型
+
+| Calcit 类型 | WASM 表示 | 大小 |
+|-------------|----------|------|
+| Number (f64) | f64 | 8 bytes |
+| Bool | i32 (0/1) | 4 bytes |
+| Tag | i32 (编译期整数) | 4 bytes |
+| Nil | i32 (sentinel) | 4 bytes |
+| Record | 线性内存 struct（字段连续排列） | Σ field sizes |
+| Tuple | tag(i32) + payload(线性内存) | 4 + Σ payload sizes |
+| String | host ref (externref / i32 handle) | 4 bytes |
+| Map/Set/List | host ref | 4 bytes |
+
+### 工作量
+
+大 — 需要完整的类型推导验证、内存布局设计、WAT 代码生成、host bridge 规范。
+
+## 路径三：WASM GC（远期）
+
+### 背景
+
+WASM GC proposal（2024 年起 V8/SpiderMonkey 已发布）提供：
+
+- `struct.new` / `struct.get` — 结构体
+- `array.new` / `array.get` — 数组
+- `ref` 类型 — GC 自动管理的引用
+
+### 映射
+
+| Calcit | WASM GC |
+|--------|---------|
+| Record | `(type $Person (struct (field $age f64) (field $name (ref string))))` |
+| List | `(type $List (array (ref any)))` |
+| Tuple | `(type $Tuple (struct (field $tag i32) (field $extra (ref $List))))` |
+| Map | 需要 host runtime 或自实现 hash trie |
+
+### 优势
+
+- 无需手动内存管理
+- Persistent data structure 的 structural sharing 天然映射（GC 管理引用）
+- 与 JS 互操作更自然（`externref` 直接传递）
+
+### 工作量
+
+取决于 WASM GC 生态成熟度。2026 年浏览器支持已基本到位，但工具链（assembler、debugger）仍在完善中。
+
+## 可行性矩阵
+
+| 维度 | 路径一（解释器→WASM） | 路径二（AOT→WASM） | 路径三（WASM GC） |
+|------|---------------------|-------------------|-----------------|
+| 语言覆盖 | 100%（完整解释器） | ~40%（纯函数子集） | ~70%（加 GC 后扩展） |
+| 性能 | 中（解释开销） | 高（原生 WASM） | 高 |
+| 工作量 | 小 | 大 | 大 |
+| 类型要求 | 无 | 全量类型标注 | 大部分类型标注 |
+| 依赖 | wasm-bindgen | 无额外 | WASM GC runtime |
+| 适用场景 | playground/REPL | 热路径加速 | 通用 WASM 编译目标 |
+
+## 建议路线
+
+1. **近期**: 路径一 — 尝试 `cargo build --target wasm32-unknown-unknown --lib` 确认编译通过，排查剩余链接错误
+2. **中期**: 路径二的子集 — 从纯数值计算函数开始，生成 WASM 模块作为 JS codegen 的"加速岛"（hot island），由 JS 运行时按需调用
+3. **远期**: 路径三 — 随 WASM GC 工具链成熟，逐步扩展可编译子集
+
+## 验证第一步
+
+```bash
+# 在 Cargo.toml 添加:
+# [lib]
+# crate-type = ["cdylib", "rlib"]
+
+# 然后尝试:
+cargo build --target wasm32-unknown-unknown --lib 2>&1 | head -50
+```
+
+输出的链接错误即为需要 `cfg` 门控的最终清单。