@calcit/procs 0.10.7 → 0.10.8

package/drafts/assert-types-plan.md

@@ -60,7 +60,7 @@ scope_types.insert(Arc::from("user"), Arc::new(test_record));
 | 阶段 2：语法解析         | Cirru→Calcit 过程识别 `assert-type`、`hint-fn` 并保留 AST 注解                | `cr --check-only` 示例                    |
 | 阶段 3：类型传播         | `preprocess_*` 传递 `ScopeTypes` 并在 `Local` 中带上 `type_info`              | demo 函数 + `&inspect-type` helper        |
 | 阶段 4：Record 静态校验  | 校验 `Record` 字段、提供错误定位、覆盖 `&record:get`/`.-field`                | 合法/非法调用示例 + `cr query error` 输出 |
-| 阶段 5：运行时与内置函数 | `&inspect-type` 原语、内置函数签名、`unknown` 回退策略                        | 运行时示例 + 文档/测试                    |
+| 阶段 5：运行时与内置函数 | `&inspect-type` 原语、内置函数签名、`dynamic` 回退策略                        | 运行时示例 + 文档/测试                    |
 
 > 阶段 1~3 已交付；表格保留原路线，方便追踪阶段 4/5 的补完情况。
 

package/drafts/assert-types.md

@@ -7,7 +7,7 @@
 - 在宏展开后的 IR (Intermediate Representation) 中，为 `Local` 变量关联类型信息。
 - 支持 `assert-type` 和 `hint-fn` 语法进行函数参数、返回值类型标记。
 - 自动利用 `Record` 信息进行方法调用（Method Call）的静态验证。
-- 允许 `unknown` 类型，并提供运行时查看手段。
+- 允许 `dynamic` 类型，并提供运行时查看手段。
 - 为内置函数补充类型提示，保持向后兼容。
 
 ## 2. 技术方案建议
@@ -123,8 +123,8 @@ defn add-numbers (a b)
 
 #### 2.0.6 未标注类型的处理
 
-- 默认所有未标注的变量 `type_info` 为 `None`，对应 `unknown` 类型
-- `unknown` 类型不触发静态类型检查
+- 默认所有未标注的变量 `type_info` 为 `None`，对应 `dynamic` 类型
+- `dynamic` 类型不触发静态类型检查
 - 保持向后兼容：老代码无需修改即可运行
 
 #### 2.0.7 类型系统定位与范围
@@ -388,7 +388,7 @@ pub struct FnInfo {
 
 - `return_type`: 通过 `hint-fn $ return-type :type` 声明
 - `arg_types`: 通过 `assert-type arg :type` 在函数体内收集
-- 默认值为 `None`，表示 `unknown` 类型
+- 默认值为 `None`，表示 `dynamic` 类型
 
 ### 2.2 预处理器增强 (`preprocess.rs`)
 
@@ -430,7 +430,7 @@ pub struct FnInfo {
     - 逻辑运算：`not` - `bool -> bool`
     - 类型检查：`type-of` - `any -> tag`
   - 可以逐步扩展更多 Proc 的类型信息
-- **兼容性**：老代码保持 `type_info` 为 `None` (即 `unknown`)，不进行强校验。
+- **兼容性**：老代码保持 `type_info` 为 `None` (即 `dynamic`)，不进行强校验。
 
 ### 2.4 运行时支持
 

package/drafts/last-session.md

@@ -0,0 +1,199 @@
+# Enum Tuple Runtime Validation - Session Summary
+
+## 已完成的工作
+
+### 1. Rust 侧实现
+
+- ✅ **新增函数** (`src/builtins/meta.rs`):
+  - `new_enum_tuple()`: `%%::` 操作符，创建带 enum 元数据的 tuple 并验证
+  - `tuple_enum()`: 获取 tuple 的 enum 原型
+  - `tuple_enum_has_variant()`: 检查 enum 是否有指定 variant
+  - `tuple_enum_variant_arity()`: 获取 variant 的参数个数
+- ✅ **验证逻辑**: 在创建时检查 tag 是否存在于 enum，arity 是否匹配
+- ✅ **单元测试**: 23 个 Rust 单元测试全部通过
+
+### 2. TypeScript 侧实现
+
+- ✅ **CalcitTuple 类增强** (`ts-src/js-tuple.mts`):
+  - 添加 `enum` 属性存储 enum 原型
+  - 更新构造函数和 `assoc` 方法
+- ✅ **新增导出函数** (`ts-src/calcit.procs.mts`):
+  - `_$n_tuple_$o_enum()`: 获取 enum 原型
+  - `_$n_tuple_$o_enum_has_variant()`: 检查 variant 存在性
+  - `_$n_tuple_$o_enum_variant_arity()`: 获取 variant arity
+  - `_PCT__PCT__$o__$o_()`: `%%::` 操作符实现
+- ✅ **代码优化**: 使用 CalcitRecord 的 `contains()` 和 `getOrNil()` 方法
+
+### 3. 核心库更新
+
+- ✅ **函数定义** (`src/cirru/calcit-core.cirru`):
+  - 添加 `&tuple:enum`, `&tuple:enum-has-variant?`, `&tuple:enum-variant-arity` 标记为 `&runtime-inplementation`
+
+### 4. 测试状态
+
+- ✅ 完整测试套件（`yarn check-all`）全部通过
+- ✅ Rust 解释器和 JavaScript 编译模式都正常工作
+
+---
+
+## 发现的核心问题 ⚠️
+
+### 问题：EDN 反序列化丢失 enum 元数据
+
+**现象：**
+从 `compact.cirru` 加载的代码中，tuple 的 enum 元数据丢失。
+
+**根本原因：**
+在 `src/data/edn.rs:132`，EDN 反序列化时硬编码设置：
+
+```rust
+Edn::Tuple(EdnTupleView { tag, extra }) => Calcit::Tuple(CalcitTuple {
+  tag: Arc::new(edn_to_calcit(tag, options)),
+  extra: extra.iter().map(|x| edn_to_calcit(x, options)).collect(),
+  class: None,
+  sum_type: None,  // ← 问题所在！
+}),
+```
+
+**影响范围：**
+
+- ✅ **直接调用有效**: REPL、`cr eval` 中使用 `%%::` 会正常验证
+- ❌ **文件加载失效**: 从 snapshot 加载的代码，tuple 的 `sum_type` 为 `None`
+- ❌ **tag-match 验证无效**: 因为无法获取 enum 元数据，所以 tag-match 中的验证被跳过
+
+**验证流程对比：**
+
+| 场景                         | enum 元数据 | 验证效果          |
+| ---------------------------- | ----------- | ----------------- |
+| `cr eval "(%%:: C E :ok 1)"` | ✅ 保留     | ✅ 创建时验证有效 |
+| 从 compact.cirru 加载        | ❌ 丢失     | ❌ 无法验证       |
+
+**证据：**
+运行测试时 tuple 显示 `(%%:: :ok 42 (:class ResultClass) (:enum Result))`，说明序列化时保存了 enum 信息（见 `src/codegen/gen_ir.rs:380`），但反序列化时没有恢复。
+
+---
+
+## 未来改进计划
+
+### 短期方案（已实现）
+
+- ✅ 依赖创建时验证（`%%::` 调用时）
+- ✅ 移除了 tag-match 中无效的验证代码
+- ✅ 确保现有功能正常工作
+
+### 中期方案（待实现）
+
+**修复 EDN 反序列化，恢复 enum 元数据**
+
+需要修改的文件：
+
+1. `src/data/edn.rs` - 反序列化逻辑
+
+   - 解析 tuple 的 `:enum` 标签
+   - 在 program/snapshot 中查找对应的 enum 定义
+   - 恢复 `sum_type` 字段
+
+2. 可能的实现思路：
+
+   ```rust
+   // 伪代码
+   Edn::Tuple(EdnTupleView { tag, extra }) => {
+     let mut tuple = CalcitTuple {
+       tag: Arc::new(edn_to_calcit(tag, options)),
+       extra: extra.iter().map(|x| edn_to_calcit(x, options)).collect(),
+       class: None,
+       sum_type: None,
+     };
+
+     // 检查是否有 :enum 标签
+     if let Some(enum_name) = get_enum_tag(&extra) {
+       // 从 program 中查找 enum 定义
+       if let Some(enum_def) = program.find_enum(enum_name) {
+         tuple.sum_type = Some(Arc::new(enum_def));
+       }
+     }
+
+     Calcit::Tuple(tuple)
+   }
+   ```
+
+3. 挑战：
+   - 需要访问 program/snapshot 上下文
+   - EDN 解析器目前是无状态的
+   - 可能需要重构 `edn_to_calcit` 函数签名
+
+### 长期方案（可选）
+
+**静态类型检查**
+
+- 在编译/preprocessing 阶段检查 enum 使用
+- 无需依赖运行时元数据
+- 需要类型推导系统支持
+
+---
+
+## 当前状态
+
+### 可用功能
+
+- ✅ `%%:: Class Enum :tag payload...` 创建 enum tuple 并验证
+- ✅ `&tuple:enum tuple` 获取 enum 原型（仅运行时创建的有效）
+- ✅ `&tuple:enum-has-variant? enum tag` 检查 variant
+- ✅ `&tuple:enum-variant-arity enum tag` 获取 arity
+
+### 已知限制
+
+- ⚠️ 从文件加载的代码无法进行 enum 验证
+- ⚠️ tag-match 中无法检查 enum 信息
+- ⚠️ 需要用户确保使用 `%%::` 创建 enum tuple
+
+### 测试文件
+
+- `calcit/test-sum-types.cirru` - 基本 enum 功能测试
+- `calcit/test-enum-validation.cirru` - 创建时验证测试
+- `calcit/test-tag-match-validation.cirru` - tag-match 验证测试（当前受限）
+
+---
+
+## 相关文件
+
+### 核心实现
+
+- `src/builtins/meta.rs` - Rust 侧函数实现
+- `src/calcit/proc_name.rs` - Proc 枚举定义
+- `src/builtins.rs` - 内置函数映射
+- `src/cirru/calcit-core.cirru` - Calcit 核心库定义
+- `ts-src/js-tuple.mts` - TypeScript Tuple 类
+- `ts-src/calcit.procs.mts` - TypeScript 导出函数
+
+### 需要修改的文件
+
+- `src/data/edn.rs` - EDN 反序列化（待修复）
+- `src/codegen/gen_ir.rs` - IR 生成（已正确序列化 enum）
+
+---
+
+## 后续步骤
+
+1. **确认需求优先级**：
+
+   - 是否需要立即修复 EDN 反序列化？
+   - 或者当前的创建时验证已经足够？
+
+2. **如果修复 EDN**：
+
+   - 研究 `edn_to_calcit` 函数调用链
+   - 设计上下文传递机制
+   - 实现 enum 定义查找
+   - 添加测试验证
+
+3. **文档更新**：
+   - 说明 enum tuple 的使用方式
+   - 注明当前限制
+   - 提供最佳实践指南
+
+---
+
+**最后更新**: 2026-01-15
+**当前分支**: enum-validation
+**测试状态**: ✅ 全部通过 (yarn check-all)

package/lib/calcit.procs.mjs

@@ -269,7 +269,65 @@ export let _$n_tuple_$o_with_class = function (x, y) {
         throw new Error("&tuple:with-class expects a tuple");
     if (!(y instanceof CalcitRecord))
         throw new Error("&tuple:with-class expects second argument in record");
-    return new CalcitTuple(x.tag, x.extra, y);
+    return new CalcitTuple(x.tag, x.extra, y, x.enumPrototype);
+};
+export let _$n_tuple_$o_enum = function (x) {
+    if (arguments.length !== 1)
+        throw new Error("&tuple:enum takes 1 argument");
+    if (!(x instanceof CalcitTuple))
+        throw new Error("&tuple:enum expects a tuple");
+    return x.enumPrototype ?? null;
+};
+const assert_enum_tag_args = (procName, enumPrototype, variantTag) => {
+    if (!(enumPrototype instanceof CalcitRecord)) {
+        throw new Error(`${procName} expects enum prototype as first argument`);
+    }
+    if (!(variantTag instanceof CalcitTag)) {
+        throw new Error(`${procName} expects tag as second argument`);
+    }
+};
+export let _$n_tuple_$o_enum_has_variant = function (enumPrototype, variantTag) {
+    if (arguments.length !== 2)
+        throw new Error("&tuple:enum-has-variant? takes 2 arguments");
+    assert_enum_tag_args("&tuple:enum-has-variant?", enumPrototype, variantTag);
+    return enumPrototype.contains(variantTag);
+};
+export let _$n_tuple_$o_enum_variant_arity = function (enumPrototype, variantTag) {
+    if (arguments.length !== 2)
+        throw new Error("&tuple:enum-variant-arity takes 2 arguments");
+    assert_enum_tag_args("&tuple:enum-variant-arity", enumPrototype, variantTag);
+    const variant = enumPrototype.getOrNil(variantTag);
+    if (variant === undefined) {
+        throw new Error(`Variant ${variantTag.value} not found in enum ${enumPrototype.name.value}`);
+    }
+    if (variant instanceof CalcitSliceList) {
+        return variant.len();
+    }
+    throw new Error("Expected variant to be a list");
+};
+export let _$n_tuple_$o_validate_enum = function (tuple, tag) {
+    if (arguments.length !== 2)
+        throw new Error("&tuple:validate-enum takes 2 arguments");
+    if (!(tuple instanceof CalcitTuple))
+        throw new Error("&tuple:validate-enum expects a tuple as first argument");
+    if (tuple.enumPrototype == null) {
+        return null;
+    }
+    assert_enum_tag_args("&tuple:validate-enum", tuple.enumPrototype, tag);
+    const tagValue = tag;
+    const variant = tuple.enumPrototype.getOrNil(tagValue);
+    if (variant === undefined) {
+        throw new Error(`enum does not have variant ${tagValue.value} for ${tuple}`);
+    }
+    if (variant instanceof CalcitSliceList) {
+        const expected = variant.len();
+        const actual = tuple.extra.length;
+        if (expected !== actual) {
+            throw new Error(`enum variant expects ${expected} payload(s), got ${actual} for ${tuple}`);
+        }
+        return null;
+    }
+    throw new Error("Expected variant to be a list");
 };
 export let _$n_record_$o_get = function (xs, k) {
     if (arguments.length !== 2) {
@@ -1204,6 +1262,26 @@ export let _$o__$o_ = (tagName, ...extra) => {
 export let _PCT__$o__$o_ = (klass, tag, ...extra) => {
     return new CalcitTuple(tag, extra, klass);
 };
+export let _PCT__PCT__$o__$o_ = (klass, enumPrototype, tag, ...extra) => {
+    // Runtime validation: check if tag exists in enum and arity matches
+    assert_enum_tag_args("%%::", enumPrototype, tag);
+    const tagValue = tag;
+    const variantDefinition = enumPrototype.getOrNil(tagValue);
+    if (variantDefinition === undefined) {
+        throw new Error(`Enum ${enumPrototype.name.value} does not have variant ${tagValue.value}`);
+    }
+    if (variantDefinition instanceof CalcitSliceList) {
+        const expectedArity = variantDefinition.len();
+        const actualArity = extra.length;
+        if (expectedArity !== actualArity) {
+            throw new Error(`Variant ${tagValue.value} expects ${expectedArity} payload(s), but got ${actualArity}`);
+        }
+    }
+    else {
+        throw new Error(`Expected variant definition to be a list, got ${variantDefinition}`);
+    }
+    return new CalcitTuple(tag, extra, klass, enumPrototype);
+};
 // mutable place for core to register
 let calcit_builtin_classes = {
     number: null,

package/lib/js-tuple.mjs

@@ -1,10 +1,11 @@
 import { _$n__$e_, toString } from "./calcit-data.mjs";
 import { CalcitRecord } from "./js-record.mjs";
 export class CalcitTuple {
-    constructor(tagName, extra, klass) {
+    constructor(tagName, extra, klass, enumPrototype = null) {
         this.tag = tagName;
         this.extra = extra;
         this.klass = klass;
+        this.enumPrototype = enumPrototype;
         this.cachedHash = null;
     }
     get(n) {
@@ -15,17 +16,17 @@ export class CalcitTuple {
             return this.extra[n - 1];
         }
         else {
-            throw new Error("Tuple only have 2 elements");
+            throw new Error(`Tuple only have ${this.extra.length + 1} elements`);
         }
     }
     assoc(n, v) {
         if (n === 0) {
-            return new CalcitTuple(v, this.extra, this.klass);
+            return new CalcitTuple(v, this.extra, this.klass, this.enumPrototype);
         }
         else if (n - 1 < this.extra.length) {
             let next_extra = this.extra.slice();
             next_extra[n - 1] = v;
-            return new CalcitTuple(this.tag, next_extra, this.klass);
+            return new CalcitTuple(this.tag, next_extra, this.klass, this.enumPrototype);
         }
         else {
             throw new Error(`Tuple only have ${this.extra.length} elements`);

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.10.7",
+    "version": "0.10.8",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.6",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.10.7",
+  "version": "0.10.8",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.6",

package/ts-src/calcit.procs.mts

@@ -300,7 +300,70 @@ export let _$n_tuple_$o_with_class = function (x: CalcitTuple, y: CalcitRecord)
   if (arguments.length !== 2) throw new Error("&tuple:with-class takes 2 arguments");
   if (!(x instanceof CalcitTuple)) throw new Error("&tuple:with-class expects a tuple");
   if (!(y instanceof CalcitRecord)) throw new Error("&tuple:with-class expects second argument in record");
-  return new CalcitTuple(x.tag, x.extra, y);
+  return new CalcitTuple(x.tag, x.extra, y, x.enumPrototype);
+};
+
+export let _$n_tuple_$o_enum = function (x: CalcitTuple) {
+  if (arguments.length !== 1) throw new Error("&tuple:enum takes 1 argument");
+  if (!(x instanceof CalcitTuple)) throw new Error("&tuple:enum expects a tuple");
+  return x.enumPrototype ?? null;
+};
+
+const assert_enum_tag_args = (procName: string, enumPrototype: CalcitRecord, variantTag: CalcitTag) => {
+  if (!(enumPrototype instanceof CalcitRecord)) {
+    throw new Error(`${procName} expects enum prototype as first argument`);
+  }
+  if (!(variantTag instanceof CalcitTag)) {
+    throw new Error(`${procName} expects tag as second argument`);
+  }
+};
+
+export let _$n_tuple_$o_enum_has_variant = function (enumPrototype: CalcitRecord, variantTag: CalcitTag) {
+  if (arguments.length !== 2) throw new Error("&tuple:enum-has-variant? takes 2 arguments");
+  assert_enum_tag_args("&tuple:enum-has-variant?", enumPrototype, variantTag);
+  return enumPrototype.contains(variantTag);
+};
+
+export let _$n_tuple_$o_enum_variant_arity = function (enumPrototype: CalcitRecord, variantTag: CalcitTag) {
+  if (arguments.length !== 2) throw new Error("&tuple:enum-variant-arity takes 2 arguments");
+  assert_enum_tag_args("&tuple:enum-variant-arity", enumPrototype, variantTag);
+
+  const variant = enumPrototype.getOrNil(variantTag);
+  if (variant === undefined) {
+    throw new Error(`Variant ${variantTag.value} not found in enum ${enumPrototype.name.value}`);
+  }
+
+  if (variant instanceof CalcitSliceList) {
+    return variant.len();
+  }
+  throw new Error("Expected variant to be a list");
+};
+
+export let _$n_tuple_$o_validate_enum = function (tuple: CalcitValue, tag: CalcitValue): CalcitValue {
+  if (arguments.length !== 2) throw new Error("&tuple:validate-enum takes 2 arguments");
+  if (!(tuple instanceof CalcitTuple)) throw new Error("&tuple:validate-enum expects a tuple as first argument");
+  if (tuple.enumPrototype == null) {
+    return null;
+  }
+
+  assert_enum_tag_args("&tuple:validate-enum", tuple.enumPrototype, tag as CalcitTag);
+
+  const tagValue = tag as CalcitTag;
+  const variant = tuple.enumPrototype.getOrNil(tagValue);
+  if (variant === undefined) {
+    throw new Error(`enum does not have variant ${tagValue.value} for ${tuple}`);
+  }
+
+  if (variant instanceof CalcitSliceList) {
+    const expected = variant.len();
+    const actual = tuple.extra.length;
+    if (expected !== actual) {
+      throw new Error(`enum variant expects ${expected} payload(s), got ${actual} for ${tuple}`);
+    }
+    return null;
+  }
+
+  throw new Error("Expected variant to be a list");
 };
 
 export let _$n_record_$o_get = function (xs: CalcitValue, k: CalcitTag) {
@@ -1291,6 +1354,31 @@ export let _PCT__$o__$o_ = (klass: CalcitRecord, tag: CalcitValue, ...extra: Cal
   return new CalcitTuple(tag, extra, klass);
 };
 
+export let _PCT__PCT__$o__$o_ = (klass: CalcitRecord, enumPrototype: CalcitRecord, tag: CalcitValue, ...extra: CalcitValue[]): CalcitTuple => {
+  // Runtime validation: check if tag exists in enum and arity matches
+  assert_enum_tag_args("%%::", enumPrototype, tag as CalcitTag);
+  const tagValue = tag as CalcitTag;
+
+  const variantDefinition = enumPrototype.getOrNil(tagValue);
+  if (variantDefinition === undefined) {
+    throw new Error(`Enum ${enumPrototype.name.value} does not have variant ${tagValue.value}`);
+  }
+
+  if (variantDefinition instanceof CalcitSliceList) {
+    const expectedArity = variantDefinition.len();
+    const actualArity = extra.length;
+    if (expectedArity !== actualArity) {
+      throw new Error(
+        `Variant ${tagValue.value} expects ${expectedArity} payload(s), but got ${actualArity}`
+      );
+    }
+  } else {
+    throw new Error(`Expected variant definition to be a list, got ${variantDefinition}`);
+  }
+
+  return new CalcitTuple(tag, extra, klass, enumPrototype);
+};
+
 // mutable place for core to register
 let calcit_builtin_classes = {
   number: null as CalcitRecord,

package/ts-src/js-tuple.mts

@@ -8,11 +8,13 @@ export class CalcitTuple {
   tag: CalcitValue;
   extra: CalcitValue[];
   klass: CalcitRecord;
+  enumPrototype: CalcitRecord;
   cachedHash: Hash;
-  constructor(tagName: CalcitValue, extra: CalcitValue[], klass: CalcitRecord) {
+  constructor(tagName: CalcitValue, extra: CalcitValue[], klass: CalcitRecord, enumPrototype: CalcitRecord = null) {
     this.tag = tagName;
     this.extra = extra;
     this.klass = klass;
+    this.enumPrototype = enumPrototype;
     this.cachedHash = null;
   }
   get(n: number) {
@@ -21,16 +23,16 @@ export class CalcitTuple {
     } else if (n - 1 < this.extra.length) {
       return this.extra[n - 1];
     } else {
-      throw new Error("Tuple only have 2 elements");
+      throw new Error(`Tuple only have ${this.extra.length + 1} elements`);
     }
   }
   assoc(n: number, v: CalcitValue) {
     if (n === 0) {
-      return new CalcitTuple(v, this.extra, this.klass);
+      return new CalcitTuple(v, this.extra, this.klass, this.enumPrototype);
     } else if (n - 1 < this.extra.length) {
       let next_extra = this.extra.slice();
       next_extra[n - 1] = v;
-      return new CalcitTuple(this.tag, next_extra, this.klass);
+      return new CalcitTuple(this.tag, next_extra, this.klass, this.enumPrototype);
     } else {
       throw new Error(`Tuple only have ${this.extra.length} elements`);
     }