@calcit/procs 0.12.30 → 0.12.32

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

@@ -1961,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.30",
+    "version": "0.12.32",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.30",
+  "version": "0.12.32",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",

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/ts-src/calcit.procs.mts

@@ -2075,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;
 };