@calcit/procs 0.12.55 → 0.12.57

package/editing-history/2026-03-13-2216-validate-struct-type-arg-arity.md

@@ -1,24 +0,0 @@
-# 2026-03-13 22:16 validate struct type arg arity
-
-## 背景
-
-发现类型注解里可以写出 `:: Pair :number :string` 这样的形式，即使 `Pair` 是非泛型 `defstruct`。旧逻辑会把后续类型参数直接附着到 `Struct(...)` 注解上，但并不会校验 `generics` 个数，最终在值匹配时只看 struct 名字，导致漏检。
-
-## 本次修改
-
-- 在 `src/calcit/type_annotation.rs` 为 `CalcitTypeAnnotation` / `CalcitFnTypeAnnotation` 增加 `validate_applied_type_args()`。
-- 对 `Struct` 注解增加规则：
-  - 非泛型 struct 不允许携带类型参数；
-  - 泛型 struct 必须严格匹配声明的类型参数个数。
-- 对 `Enum` 注解增加保守规则：当前不接受额外类型参数。
-- 在 `src/builtins/records.rs` 中，`defstruct` 字段类型解析后立即做校验。
-- 在 `src/calcit/sum_type.rs` 中，`defenum` payload 类型解析后立即做校验。
-- 在 `src/calcit/sum_type.rs` 与 `src/calcit/type_annotation.rs` 补充回归测试，覆盖：
-  - 非泛型 struct 带类型参数时报错；
-  - 泛型 struct 类型参数个数不匹配时报错；
-  - enum payload 中引用非法 struct 类型注解时报错。
-- 同时修正 `calcit/test-generics.cirru` 中 `Wrapped` 的 payload 类型，把错误的 `:: Pair :number :string` 改为 `Pair`。
-
-## 结论
-
-现在像 `:: Pair :number :string` 这种写法不会再静默通过；定义期就会被校验出来，避免文档和测试继续误导后续修改。

package/editing-history/2026-03-16-2353-runtime-boundary-cleanup.md

@@ -1,14 +0,0 @@
-# Runtime Boundary Cleanup
-
-## Summary
-
-- removed the dead `CalcitImport.coord` compatibility path and the related runner parameter flow
-- renamed remaining `evaled`-era runtime lookup terminology to `runtime-ready` / `runtime cache`
-- synced the runtime boundary refactor draft with the current migration state and recent cleanup progress
-
-## Knowledge
-
-- `CalcitImport.def_id` is now the stable import-side runtime lookup anchor; the old `coord -> EntryBook` path no longer needs to be preserved in import metadata
-- type-annotation lookup registration should describe runtime-ready value lookup, not the removed evaled-store model
-- incremental reload messaging should talk about clearing runtime caches rather than evaled states to match the current architecture
-- this migration tail is now mostly about narrowing fallback bridges and improving reload coverage, not about preserving old runtime naming or lookup compatibility

package/editing-history/2026-03-17-0150-runtime-boundary-lookup-cleanup.md

@@ -1,28 +0,0 @@
-# Runtime boundary lookup cleanup
-
-## Summary
-
-- Consolidated runtime-vs-compiled lookup helpers inside `program` and removed extra `runner` bridging paths.
-- Tightened snapshot fallback and codegen metadata lookup so source-backed defs no longer silently rely on runtime-derived compiled entries.
-- Skipped runtime-only placeholder defs in JS/IR codegen and added program-level regression tests for reload invalidation and snapshot behavior.
-- Reframed the runtime-boundary draft into a closure plan focused on stabilizing compiled/runtime boundaries, adding watch-reload regression coverage, and avoiding new architectural layers.
-- Simplified `runner` and `preprocess` lookup flow by removing thin wrappers, deduplicating repeated symbol fallback order, and collapsing silent program-value reads onto shared helpers.
-- Added regression coverage for reload package clearing, source-backed snapshot rebuild after changes, compiled fallback cache behavior, and strict-vs-lenient runtime resolution semantics.
-
-## Knowledge points
-
-- Runtime execution helpers should live in `program` so `runner` only maps runtime state to evaluation flow and user-facing errors.
-- Metadata queries such as codegen type hints should prefer compiled/source schema and only fall back to ready runtime values, never by executing compiled payloads.
-- Reload invalidation needs direct transitive-dependency tests plus namespace-header coverage; otherwise runtime cache cleanup regresses quietly.
-- If compiled execution is used as a fallback read path, tests must assert it does not implicitly backfill runtime cells; otherwise compiled/runtime boundaries drift back together.
-- Keep cleanup work biased toward removing duplicate lookup order and unused parameters before introducing any new abstraction; the stable payoff is clearer boundaries with lower entity count.
-- `runner`-side error mapping for strict runtime resolution is still a meaningful boundary, but repeated namespace lookup order and required-value program reads can be shared safely.
-
-## Validation
-
-- `cargo fmt`
-- release fibo profiling during optimization review
-- `cargo test clear_runtime_caches_for_reload -- --nocapture`
-- `cargo test snapshot_rebuilds_changed_source_backed_def_after_reload_changes -- --nocapture`
-- `cargo test program::tests -- --nocapture`
-- `cargo test -q`

package/editing-history/2026-03-20-0116-json-builtins-and-runtime-docs.md

@@ -1,48 +0,0 @@
-## Summary
-
-This commit moves JSON parsing and serialization into Calcit builtins and aligns the surrounding runtime/docs/tooling updates needed to ship it cleanly.
-
-1. Added builtin JSON runtime functions
-
-- Introduced `json-parse`, `json-stringify`, and `json-pretty` in Rust builtin dispatch and JS runtime exports.
-- Added fast arity/type checks on exposed runtime entry points.
-- Normalized integer-valued numbers to encode as JSON integers in Rust, matching JS output.
-- Added native tests and Calcit-level coverage for parse/stringify/pretty behavior and error paths.
-
-2. Updated core docs and runtime placeholder naming
-
-- Added `calcit.core` docs/examples for the JSON runtime functions.
-- Renamed the runtime placeholder spelling from `runtime-inplementation` to `runtime-implementation` across core snapshot metadata and Rust handling.
-- Preserved an explicit `cr <snapshot-file> edit format` example in `docs/CalcitAgent.md`.
-
-3. Snapshot formatting workflow
-
-- Re-ran `cr edit format` against the touched Cirru snapshot files:
-  - `src/cirru/calcit-core.cirru`
-  - `calcit/test.cirru`
-
-## Files touched (high level)
-
-- Rust builtin registration and implementation for JSON runtime support.
-- JS runtime proc exports for JSON behavior and validation.
-- Calcit core snapshot docs/examples and test snapshot updates.
-- CLI/codegen placeholder spelling cleanup.
-- Agent guide example for `edit format`.
-
-## Validation notes
-
-- `cargo test json_`
-- `cargo test validate_runtime_impl_is_skipped -- --nocapture`
-- `cargo test runtime_placeholder -- --nocapture`
-- `cargo run --bin cr -- calcit/test.cirru -1`
-- `yarn check-all`
-
-## Release size check
-
-Measured `target/release/cr` against `HEAD` using a detached worktree build:
-
-- Current: `5192960` bytes (`5.0M`)
-- Base: `5174400` bytes (`4.9M`)
-- Delta: `+18560` bytes (about `+18.1 KiB`)
-
-Conclusion: the builtin JSON work increases the release binary size slightly, but the delta is small relative to the ~5 MB target.

package/editing-history/2026-03-26-2013-docs-frontmatter-and-module-search.md

@@ -1,58 +0,0 @@
-# Docs frontmatter 与模块检索整理
-
-## 变更概述
-
-- 为 `cr docs search/read/read-lines` 增加 `scope/module` 维度，支持核心文档、模块文档和跨域检索。
-- 为 core docs 建立统一的 frontmatter 规范，并补充 `title/scope/kind/category/aliases/entry_for` 元数据。
-- 将 `docs` 检索逻辑从纯文件名匹配升级为结合 frontmatter、路径、标题与条目词的综合解析与排序。
-- 给文档系统补充规范页与验证页，方便后续扩展 `cr docs` 时保持行为稳定。
-- 调整 Cirru 校验错误提示，让“其实是字符串”的场景给出更直接的修复建议。
-
-## 关键实现
-
-- `src/cli_args.rs`
-  - 为 `docs search`、`docs read`、`docs read-lines` 增加 `--scope`、`--module` 参数。
-
-- `src/bin/cli_handlers/command_echo.rs`
-  - 同步回显新增 docs 参数，确保工具模式下能看到完整检索上下文。
-
-- `src/bin/cli_handlers/docs.rs`
-  - 引入 `GuideDocFrontmatter`、`GuideDocScope`、`DocsSearchScope`。
-  - 支持解析 Markdown frontmatter，并在加载时校验 `category`。
-  - 支持从 core docs 与 `~/.config/calcit/modules/<module>/docs/` 同时加载文档。
-  - 统一 `search/read/read-lines` 的查询解析逻辑，允许通过文件名、路径片段、标题、`aliases`、`entry_for` 命中目标。
-  - 增加更偏向 guide/reference 页的排序策略，减少 spec/索引页抢占结果。
-  - 抽出 `match_score`、`accumulate_match_score`、`parse_guide_doc` 等辅助函数，压缩主文件重复逻辑。
-
-- `src/bin/cli_handlers/docs_tests.rs`
-  - 将 docs 相关测试从 `docs.rs` 拆出，单独维护解析、排序、模块加载与校验场景。
-
-- `docs/docs-indexing.md`
-  - 固化 frontmatter 字段、分类注册表、scope 布局与 authoring 约束。
-
-- `docs/docs-validation.md`
-  - 记录 `cr docs` 的可执行回归命令，覆盖 `search/read/read-lines` 与 module scope。
-
-- `src/bin/cli_handlers/cirru_validator.rs`
-  - 当 token 更像“应写成字符串的文本”时，提示使用 `|text` 或 `"|text with spaces"`，减少样式值与括号文本误写的排查成本。
-
-## 文档整理原则
-
-- `category` 只允许稳定注册值，避免搜索元数据失控膨胀。
-- `aliases` 主要承接用户会直接输入的别名或术语，`entry_for` 主要承接命令/API/任务入口。
-- `Agents.md` 与普通 docs 页复用同一套 frontmatter 机制，但渲染时默认隐藏元数据正文。
-- 模块领域知识保留在模块 docs 中，Calcit core 只提供通用索引与加载能力，不内置 Respo 特殊语义。
-
-## 验证
-
-- `cargo fmt`
-- `cargo test docs --bin cr`
-- 手动验证：
-  - `cargo run --bin cr -- docs search target-replace`
-  - `cargo run --bin cr -- docs search 'cr eval'`
-  - `cargo run --bin cr -- docs read polymorphism.md`
-
-## 后续经验
-
-- docs 元数据一旦进入 CLI 行为，就应该配套规范页与验证页，否则后续加字段很容易出现“文档能写、检索却不稳定”的分叉。
-- 模块文档检索要尽量和 core docs 走同一套 resolver，这样使用者不需要记两套命令心智模型。

package/editing-history/2026-04-07-1550-path-format-at-prefix-migration.md

@@ -1,46 +0,0 @@
-## Path format migration: `@` prefix for display paths
-
-### What changed
-
-All display-level Cirru tree paths now use `@` prefix notation when rendered to user.
-
-### Display format change
-
-- `1.2.3.4` → `@1.2.3.4` (bare path)
-- `[1.2.3.4]` → `[@1.2.3.4]` (bracketed path)
-- `NodeLocation::Display` now outputs `ns/def [@1.2.3]` instead of `ns/def [1.2.3]`
-
-### Backward compatibility
-
-- `parse_path()` strips leading `@` if present, so CLI input still accepts both `@1.2.3` and `1.2.3`
-- Error messages and help text updated to show `@` format
-
-### Files modified
-
-**Core functions:**
-
-- `src/bin/cli_handlers/common.rs`: `format_path()` returns `@1.2.3`; `parse_path()` strips `@` prefix; test assertions updated
-- `src/calcit.rs`: `NodeLocation::Display` outputs `[@1.2.3]`; test assertion updated
-- `src/bin/cli_handlers/cirru_validator.rs`: local `format_path()` updated
-- `src/type_coverage.rs`: `format_cirru_path()` updated
-- `src/bin/cli_handlers/chunk_display.rs`: `compare_coords()` strips `@`; test `fragment()` helper uses `@`
-- `src/runner/preprocess/mod.rs`: `[&inspect-type]` debug output uses `@`
-
-**Tree/edit handlers:**
-
-- `src/bin/cli_handlers/tree.rs`: inline path formatting in swap handler
-- `src/bin/cli_handlers/edit.rs`: error message example
-- `src/cli_args.rs`: help text examples (3 locations)
-
-**Documentation:**
-
-- `docs/CalcitAgent.md`: 19 path examples updated
-- `docs/run/agent-advanced.md`: 23 path examples updated
-- `docs/run/edit-tree.md`: 6 path examples updated
-- `docs/Respo-Agent.md` (respo project): 26 path examples updated
-
-### Why
-
-- `@` prefix helps LLMs distinguish path coordinates from other dotted numeric patterns (like version numbers or floats)
-- `@` is safe in shell (no escaping needed)
-- All display output now consistent with `@` prefix

package/editing-history/2026-04-12-1524-js-codegen-map-to-record.md

@@ -1,26 +0,0 @@
-# JS Codegen Fix for Map-to-Record Rewrite
-
-## Problem
-The map-to-record rewrite (from previous commit) inserted `Calcit::Struct` directly into the AST. The interpreter handles this, but JS codegen (`emit_js.rs` line 319) has no arm for `Calcit::Struct` → panics with `unreachable!`.
-
-## Key Insight
-The `%{}` macro normally expands to `&%{}` with a **symbol/import reference** as the first arg (not a literal `Calcit::Struct`). JS codegen relies on this — it emits the symbol as a variable reference (e.g., `Element`), and the JS runtime `_$n__PCT__$M_` function accepts the struct object at runtime.
-
-## Solution
-1. Added `resolve_to_struct_with_ref()` to `CalcitTypeAnnotation` — returns `Option<(CalcitStruct, Option<(Arc<str>, Arc<str>)>)>` with ns/def path from TypeRef annotations.
-2. Modified `try_rewrite_single_map_to_record()` to emit `Calcit::Import(CalcitImport { ... })` instead of `Calcit::Struct`:
-   - `ImportInfo::SameFile` when struct is in same namespace (avoids self-import duplicate declaration)
-   - `ImportInfo::NsReferDef` when struct is in a different namespace (generates proper cross-ns import)
-   - Falls back to `Calcit::Struct` only when no ns/def path is available
-
-## Pitfall: Self-Import Duplicate Declaration
-First attempt used `NsReferDef` for all imports — caused `SyntaxError: Identifier 'Point2D' has already been declared` because a self-import was generated when struct is in same namespace. Fix: detect `ns == file_ns` and use `SameFile`.
-
-## Verification in Respo
-- Typed `element->string` as `'respo.schema/Element`, `make-string` as `'respo.schema/Component`
-- Test passes `{}` map to `element->string` → auto-rewritten to `%{} Element ...` record construction
-- Generated JS: `import { Element } from "./respo.schema.mjs"` + `$clt._$n__PCT__$M_(Element, ...)`
-
-## Files Changed
-- `src/calcit/type_annotation.rs`: Added `resolve_to_struct_with_ref()`
-- `src/runner/preprocess.rs`: Emit Import reference in `try_rewrite_single_map_to_record()`

package/editing-history/2026-04-12-1549-map-to-record-field-validation.md

@@ -1,29 +0,0 @@
-# Map-to-Record Field Validation and Nil Fill
-
-## Problem
-Map-to-record rewrite was passing through ALL map keys without validation, and emitting only
-the keys present in the map. This caused:
-1. Maps with keys not in the struct (e.g., `:x`) being incorrectly rewritten to records
-2. "fields size does not match" runtime error when the map has fewer keys than struct fields
-
-## Fix (preprocess.rs)
-1. **Field validation**: Check each map key against `struct_def.fields`. If any key is not a
-   valid struct field, skip the rewrite entirely (stay as map).
-2. **Nil fill**: Emit ALL struct fields in definition order. For fields not present in the map,
-   emit `Calcit::Nil`. This ensures the record always has the correct field count.
-3. **HashMap tracking**: Build a `HashMap<EdnTag, &Calcit>` of provided fields for O(1) lookup
-   during emission.
-
-## Key Types
-- `struct_def.fields` is `Vec<EdnTag>` — compare with `EdnTag` directly, not `Arc<str>`
-- `provided_fields` is `HashMap<EdnTag, &Calcit>` — avoids the `Arc<str>: Borrow<EdnTag>` issue
-
-## Respo DomProps Design
-- 29 fields with `(:: :optional <type>)` annotations
-- Strings: class-name, id, type, href, src, placeholder, name, title, data-name, data-comp, target
-- Dynamic: style (map), value, inner-text
-- Bools: disabled, checked, spell-check, read-only, selected
-- Number: tab-index
-- Fns: on-click, on-input, on-focus, on-blur, on-keydown, on-keyup, on-change
-- Maps: on, event
-- `create-element`/`create-list-element` convert record props to map via `&record:to-map`

package/editing-history/2026-04-13-1600-tuple-to-enum-rewrite.md

@@ -1,13 +0,0 @@
-## 概要
-
-为 tuple-to-enum 自动改写实现预处理阶段支持。当函数参数 schema 标注为 enum 类型时,
-调用者传递的 untyped tuple `:: :tag payload` 自动改写为 `%:: Enum :tag payload`。
-
-## 知识点
-
-- `CalcitTypeAnnotation::resolve_to_enum_with_ref()` 对应 struct 端已有的 `resolve_to_struct_with_ref()`
-- `resolve_enum_from_program()` 通过 `lookup_runtime_ready_registered` + `lookup_def_code_registered` 两级缓存查找
-- tuple 改写只替换 head proc (`NativeTuple` → `NativeEnumTupleNew`) 并插入 enum 引用，不对 tag/payload 做验证（由 `check_enum_tuple_construction` 兜底）
-- JS codegen 需要 `Calcit::Import` 而非 `Calcit::Enum` 内联值，通过 TypeRef 路径判断走 SameFile 还是 NsReferDef
-- map-to-record 改写验证 key 合法性，tuple-to-enum 改写不验证（差异源于 struct field 是封闭集合，enum tag 验证已有独立检查）
-- Cirru tag-match 零载荷变体的 pattern 是 `(:ok)` 而非 `:ok`（后者在 pair 中被当作 body）

package/editing-history/2026-04-13-2309-typeslot-enum-compile-safety.md

@@ -1,45 +0,0 @@
-# TypeSlot + Enum 编译期安全增强
-
-## 概要
-
-让 `deftype-slot` / `bind-type` 机制真正实现编译期 enum variant 校验。此前 TypeSlot 绑定的 enum 在自动推导 (`:: → %::`) 路径上缺乏变体验证，导致拼写错误或不存在的 variant 无法在 `cr js` / `--check-only` 时报出。
-
-## 修改的文件
-
-### `src/calcit/type_annotation.rs`
-
-- `resolve_to_enum_with_ref()`: 新增 `TypeSlot` 分支，通过 `resolve_type_slot()` 解析绑定类型后委托
-- `matches_with_bindings()`: 双向 `Tuple/Enum` 匹配 — 原先只有 `(Tuple, Enum)` 方向，TypeSlot 解析后顺序会翻转，新增 `(Enum, Tuple)` 方向
-
-### `src/calcit.rs`
-
-- 将 `resolve_type_slot` 加入 `pub use` 导出列表
-
-### `src/runner/preprocess.rs`
-
-- `resolve_enum_value()`: 在 `as_struct()` 调用前增加 TypeSlot 解析（避免 `&CalcitStruct` 生命周期问题）
-- 新增 `try_rewrite_local_fn_tuple_args_to_enum_tuples()`: 对本地函数调用（如回调 `d!`）也执行 tuple→enum 自动重写
-- 主预处理 `Calcit::Local` 分支: 增加 local fn 调用的重写+类型检查（clone 避免借用冲突）
-- `try_rewrite_single_tuple_to_enum_tuple()`: 增加变体验证 — 重写后立即检查 tag 是否是 enum 的合法 variant，不合法则发出警告
-
-### `src/bin/cr_tests/type_fail.rs`
-
-- 新增 `type_fail_type_slot_enum_invalid_variant` 测试，验证 TypeSlot 绑定的 enum 在自动重写路径下能正确检测不存在的 variant
-
-### `calcit/type-fail/type-slot-enum-invalid-variant.cirru`
-
-- 新增测试 fixture：声明 `defenum Action`、通过 TypeSlot 绑定、调用 `takes-action $ :: :nonexistent |hello`，期望产生 variant 不存在警告
-
-## 知识点
-
-1. **TypeSlot 解析链**: `TypeSlot(name) → resolve_type_slot(name) → CalcitTypeAnnotation (通常是 TypeRef)` → 再通过 `resolve_to_enum_with_ref()` 得到 enum 定义。这是一个两步间接过程。
-
-2. **`matches_with_bindings` 双向性**: TypeSlot 被解析后会调 `bound.matches_with_bindings(other, bindings)`，此时 self/other 顺序可能翻转。所有组合型匹配（如 Tuple/Enum）都需要双向 pattern。
-
-3. **`as_struct()` 返回引用**: `CalcitTypeAnnotation::as_struct()` 返回 `Option<&CalcitStruct>`，无法从临时解析结果中返回引用。修复方案是在调用点先解析 TypeSlot 再调 `as_struct()`。
-
-4. **自动重写的 `%::` 不经过 `preprocess_expr`**: `try_rewrite_single_tuple_to_enum_tuple` 构造的 `[NativeEnumTupleNew, ...]` 列表是在预处理完参数后生成的，不会经过 `check_proc_arg_types` 中的 `check_enum_tuple_construction`。因此变体验证必须在重写函数内部完成。
-
-5. **Local fn 调用缺少自动重写**: 原先只有 `CalcitFn` 调用走 `try_rewrite_tuple_args_to_enum_tuples`。`Calcit::Local` 调用（如回调参数 `d!`）需要单独处理。新函数接受 `CalcitFnTypeAnnotation` 而非 `CalcitFn`。
-
-6. **Lambda-in-map 的 EXPECTED_FN_TYPE 盲区**: `fn (e d!)` 在 hashmap 值（如 `:on-click`）中时，`d!` 不会获得 `EXPECTED_FN_TYPE` 注入的类型信息。目前通过显式 `%:: Op :variant` 写法绕过，属于已知架构限制。

package/editing-history/2026-04-14-1500-loose-record-syntax.md

@@ -1,32 +0,0 @@
-# 2026-04-14 15:00 — `?{}` 松散 Record 语法
-
-## 概要
-
-新增 `?{}` 松散 record 语法，允许不声明 struct 就创建 record，与 `::` 无类型 tuple 对称。
-在函数参数有 struct 类型标注时，预处理阶段自动改写为 `%{} StructDef ...`。
-
-## 改动文件
-
-| 文件 | 变更 |
-|------|------|
-| `src/calcit/proc_name.rs` | 新增 `NativeLooseRecord` proc 变体，`?{}` 序列化，类型签名 |
-| `src/data/cirru.rs` | `"?{}"` token 解析为 `Calcit::Proc(NativeLooseRecord)` |
-| `src/calcit/record.rs` | `LOOSE_RECORD_NAME`、`is_loose()`、`from_loose_pairs()` |
-| `src/builtins/records.rs` | `call_loose_record()` 运行时：验证 tag 键、排序、排重 |
-| `src/builtins.rs` | 分发 `NativeLooseRecord => call_loose_record(args)` |
-| `src/calcit.rs` | Display: 松散 record 显示为 `(?{} ...)` |
-| `src/runner/preprocess.rs` | `try_rewrite_loose_record_args_to_struct_records`、类型推断、skip core arg check |
-| `ts-src/js-record.mts` | JS 运行时 `_$q__$M_` 函数 |
-| `calcit/test-record.cirru` | `test-loose-record-rewrite` 集成测试 |
-| `docs/features/records.md` | 文档：松散 record 语法、自动改写、类型对称表 |
-
-## 性能优化
-
-- **预处理改写链合并重建**：三步改写（map→record、loose→struct、tuple→enum）原先每步都重建 `ys` (CalcitList)，优化为仅在有改写时统一重建一次，减少 CalcitList push 操作。
-- **JS 排序比较器修正**：将重复字段检测从 sort comparator 中移出（comparator 内 throw 违反排序契约），改为排序后线性扫描相邻元素，行为更可靠。
-
-## 知识点
-
-- `EdnTag::cmp` 按全局 tag 池分配顺序排序（整数 index），**不是**字典序。record 字段排序必须用 `ref_str().cmp()` 保持字母序。
-- CalcitList 基于 persistent ternary tree，`.clone()` 是 O(1) 引用计数操作。
-- Sort comparator 不应抛异常——不同排序算法对异常行为未定义。

package/editing-history/2026-04-14-2259-bidir-type-check-refactor.md

@@ -1,63 +0,0 @@
-# 202604142259 — Bidirectional Type Checking Architecture Refactoring
-
-## 概要
-
-将 `src/runner/preprocess.rs`（6199 行单体文件）拆分为模块化目录结构，
-按双向类型检查（bidirectional type checking）的概念分离关注点。
-
-## 改动详情
-
-### 模块拆分
-
-`preprocess.rs` → `preprocess/` 目录模块：
-
-| 模块 | 行数 | 职责 |
-|---|---|---|
-| `mod.rs` | ~4744 | 预处理核心：符号解析、宏展开、作用域管理、特殊语法 |
-| `type_inference.rs` | ~693 | 类型合成（synthesis）：自下而上推导表达式类型 |
-| `type_checking.rs` | ~402 | 类型检查（checking）：自上而下验证参数类型 |
-| `type_rewriting.rs` | ~398 | 类型定向重写：根据期望类型重写 AST 字面量 |
-
-### 代码去重
-
-1. **统一参数重写循环** (`rewrite_args_by_expected_type`)：
-   - 原先 4 个 `try_rewrite_*_args_to_*` 函数各自包含相同的外层循环（~30 LOC × 4）
-   - 提取为泛型 `rewrite_args_by_expected_type<F>` 函数，4 个入口各只保留闭包调用
-
-2. **统一参数类型检查循环** (`check_arg_types_loop`)：
-   - 原先 `check_local_fn_call_arg_types` 和 `check_user_fn_arg_types` 共享相同的
-     zip → resolve_type_value → matches_with_bindings → gen_check_warning 模式
-   - 提取为泛型 `check_arg_types_loop<F>` 函数，包含 variadic 处理和 spread 跳过逻辑
-
-3. **统一引用节点构建** (`build_struct_ref_node` / `build_enum_ref_node`)：
-   - 原先 map→record 和 loose-record→struct 各自复制 Import vs Struct/Enum 分支
-   - 提取为共享的 `build_struct_ref_node` 和 `build_enum_ref_node` 函数
-
-### Proc 推导提取
-
-- `infer_type_from_expr` 中的 `Calcit::Proc` 分支（~100 行 match arms）
-  提取为独立的 `infer_proc_call_return_type` 函数，提高可读性
-
-## 双向类型检查映射
-
-参照 Dunfield & Krishnaswami 的框架：
-
-| 方向 | 模块 | 入口函数 |
-|---|---|---|
-| **Synthesis** (⇒) | `type_inference` | `infer_type_from_expr`, `resolve_type_value` |
-| **Checking** (⇐) | `type_checking` | `check_*_arg_types`, `check_function_return_type` |
-| **Rewriting** (结构适配) | `type_rewriting` | `try_rewrite_*` |
-| **Context** (线程局部) | `mod.rs` | `EXPECTED_FN_TYPE`, `EXPECTED_STRUCT_TYPE` |
-
-## 为后续 match 语法扩展铺路
-
-- `type_checking.rs` 的 `check_arg_types_loop` 模式可直接复用于 match 分支检查
-- `type_inference.rs` 中已有 `infer_if_return_type` 作为分支合并的模板
-- 未来只需在相应模块中添加新函数，无需修改 `mod.rs` 的核心调度
-
-## 验证
-
-- `cargo check --lib` ✅ 零警告
-- `cargo clippy --lib -- -D warnings` ✅ 零警告
-- `cargo fmt` ✅ 格式一致
-- 链接器问题（`ld: library 'System' not found`）是环境问题，非代码变更引起

package/editing-history/2026-04-15-0120-match-syntax-exhaustiveness.md

@@ -1,20 +0,0 @@
-# match syntax with exhaustiveness checking
-
-## Summary
-
-Added native `match` syntax for enum pattern matching with compile-time exhaustiveness detection,
-as a safer alternative to `tag-match` macro. See `drafts/match-syntax-rfc.md` for full design.
-
-## Files modified
-
-- `src/calcit/syntax_name.rs` — `CalcitSyntax::Match`
-- `src/builtins/syntax.rs` — `syntax_match()` runtime
-- `src/builtins.rs` — dispatch entry
-- `src/runner/preprocess/mod.rs` — `preprocess_match()` with exhaustiveness
-- `src/codegen/emit_js.rs` — `gen_match_code()` JS output
-- `calcit/test-enum.cirru` — test cases
-
-## Key takeaway
-
-Cirru indentation creates pair-based `(pattern body)` children — same format as `tag-match`.
-Flat alternating format doesn't survive Cirru serialization round-trips.

package/editing-history/2026-04-15-1211-record-nth-optimization.md

@@ -1,44 +0,0 @@
-# `&record:nth` — Compile-Time Record Field Index Optimization
-
-## 概述
-
-新增 `NativeRecordNth` / `&record:nth` 过程，在预处理阶段将 record 字段访问优化为 O(1) 索引访问，绕过运行时的类型分发链和二分查找。
-
-## 优化前访问路径
-
-- `(:field record)` → 重写为 `(get arg :field)` → 运行时 6 次类型判断 (`nil?` → `string?` → `map?` → `list?` → `tuple?` → `record?`) → `&record:get` → `index_of()` O(log n) 二分查找
-- `&record:get record :field` → 运行时 `index_of()` O(log n) 二分查找
-
-## 优化后访问路径
-
-当预处理阶段可以通过 `resolve_type_value` + `as_struct()` 解析出 record 的 struct 定义时：
-
-- `(:field record)` → 直接重写为 `(&record:nth record <compile-time-idx>)` → 运行时 O(1) `values[idx]`
-- `&record:get record :field` → 重写为 `(&record:nth record <compile-time-idx>)` → 运行时 O(1)
-
-## 触发条件
-
-优化仅在类型信息明确时激活：
-- record 由 `%Struct ...` 构造器在本地 `let` 中创建
-- 函数参数有显式 struct 类型的 schema 标注
-
-若类型不明，回 fallback 到原有路径，不影响运行时行为。
-
-## 修改文件
-
-1. **`src/calcit/proc_name.rs`** — 新增 `NativeRecordNth` 变体 (`&record:nth`)，签名 `(record, number) → dynamic`
-2. **`src/builtins/records.rs`** — 实现 `record_nth(xs)` 运行时函数，直接 `values[idx]` 访问
-3. **`src/builtins.rs`** — 分发表连线 `NativeRecordNth => records::record_nth`
-4. **`src/runner/preprocess/mod.rs`** — 两个重写点：
-   - Tag-call (`Calcit::Tag` as head)：解析 arg 类型后索引重写
-   - `NativeRecordGet` proc call：解析 record arg 类型后索引重写
-5. **`src/runner/preprocess/type_inference.rs`** — `infer_record_nth_type()` 根据 struct 的 `field_types[idx]` 推断返回类型
-6. **`src/runner/preprocess/type_checking.rs`** — 将 `NativeRecordNth` 加入 core arg type check 跳过列表
-7. **`src/codegen/emit_js.rs`** — JS 内联代码生成 `record.values[idx]`，无函数调用开销
-
-## 知识点
-
-- `CalcitStruct.index_of(field_str)` 在编译期使用，用字段名解析排序位置
-- `resolve_type_value()` 返回 `None` 时优化不触发，安全回退
-- JS CalcitRecord 的 `.values` 数组和 Rust 端的 `values` Vec 索引一致（均按字段名字母序排序）
-- 对于真实项目（如 respo），函数参数通常缺少 struct 类型标注，优化暂不触发；后续若 schema 推断增强，无需改动 rewrite 逻辑即可自动生效

package/editing-history/2026-04-16-1936-predicate-narrowing-expansion.md

@@ -1,31 +0,0 @@
-# 扩展 extract_predicate_binding 支持更多类型谓词
-
-## 改动概要
-
-将 `extract_predicate_binding` 重构为 `extract_predicate_bindings`，支持双向窄化（true/false 分支），并新增 6 个类型谓词的窄化支持。
-
-## 修改文件
-
-### src/runner/preprocess/mod.rs
-
-- 重构 `extract_predicate_binding` → `extract_predicate_bindings`，返回 `PredicateNarrowing` 结构体（包含 `true_binding` 和 `false_binding`）
-- `preprocess_if` 中 false 分支也应用窄化信息
-- 新增谓词：`tag?` → `:tag`、`bool?` → `:bool`、`symbol?` → `:symbol`、`fn?` → `:fn`
-- 新增 `nil?`/`some?`：当变量已知为 `Optional(T)` 时，nil? 的 false 分支窄化为 `T`，some? 的 true 分支窄化为 `T`
-
-### src/calcit/proc_name.rs
-
-- `TurnTag` 的参数签名从 `some_tag("string")` 改为 `dynamic_tag()`，因为 `turn-tag` 在运行时接受 tag/symbol/string，旧签名在 `tag?` 窄化后误报
-
-## 知识点
-
-1. **双向窄化**：`if (nil? x) ... else ...`，false 分支可从 `Optional(T)` 解包为 `T`，这在链式 if 模式中可以传播类型信息
-2. **新窄化暴露的类型签名问题**：`tag?` 窄化后，`(turn-tag x)` 触发了 arg-type-mismatch 警告，因为 `turn-tag` 签名过严。类似 coercion 函数应使用 `dynamic_tag()`
-3. **核心库中 `if (tag? ...)` 出现 5 次、`if (nil? ...)` 26 次、`if (list? ...)` 41 次**——窄化覆盖面广
-4. **JS 端 tuple `.nth` 缺失**：prior session 简化了多态函数（移除 tuple? 分支），但 JS runtime 的 `invoke_method` 没有对应的 core-tuple-methods 注册，导致 JS 测试 `test_refs` 失败。这是 JS procs 层的问题，不是预处理阶段的问题
-
-## 测试结果
-
-- Rust: 246 tests pass（67 cirru + 179 unit）
-- Clippy: clean
-- JS: 已知 pre-existing failure（tuple .nth in JS runtime）

package/editing-history/2026-04-17-0132-monomorphize-map-filter.md

@@ -1,50 +0,0 @@
-# Monomorphize `map` / `filter` at Compile Time
-
-## 背景
-
-`try_specialize_polymorphic_call`（`src/runner/preprocess/mod.rs`）原本只能把
-`count`、`empty?`、`first`、`rest`、`nth`、`get`、`assoc`、`contains?` 等
-**built-in 多态 proc** 特化成 native proc（`NativeListCount` / `NativeMapGet`
-等），彻底避免运行时按 `type_of` 做分支。
-
-但是 Calcit 里最常见的集合高阶函数 `map` / `filter` / `reduce` 等都是在
-`calcit-core.cirru` 里用 Calcit 本身定义的用户级 defn（例如 `&list:map`、
-`&map:map`、`&set:filter`），原先不能在预处理阶段复用这套机制，运行时仍要靠
-`list?`/`map?`/`set?` 三条 `cond` 分支来分发。
-
-本次把能力扩展到 Calcit 级别的 core def，当 receiver 的静态类型可推断时，
-直接把 `(map xs f)` 改写成 `(calcit.core/&list:map xs f)` 等形式。
-
-## 关键改动
-
-- `src/runner/preprocess/mod.rs`
-  - `try_specialize_polymorphic_call` 新增 `file_ns: &str` 参数，用于构造
-    `Calcit::Import` 头的 `ImportInfo::Core { at_ns }`。
-  - 在已有的 proc 特化表之前新增一张“core def 特化表”：
-    - `("map", List(_))   -> &list:map`
-    - `("map", Map(_, _)) -> &map:map`
-    - `("filter", List(_))   -> &list:filter`
-    - `("filter", Map(_, _)) -> &map:filter`
-    - `("filter", Set(_))    -> &set:filter`
-  - 命中时直接构造 `Calcit::Import(CalcitImport { ns: "calcit.core", def, info:
-    Core { at_ns: file_ns }, def_id: Some(program::ensure_def_id(...).0) })`
-    作为新的 head，保持已 preprocess 过的参数不变，避免重复预处理。
-  - 禁止对 `&list:map` / `&map:map` / `&set:map` / `&list:filter` /
-    `&map:filter` / `&set:filter` 自身再次 monomorphize，避免潜在 cycle。
-  - 调用点 `Ok(Calcit::from(CalcitList::from(ys)))` 前的 specialize 调用传入
-    `file_ns`。
-
-## 验证
-
-- `cargo fmt && cargo clippy --release -- -D warnings` ✓
-- `cargo test --release` ✓ 所有现有测试通过
-- `yarn check-all` ✓ 全量集成测试 + WASM 测试全部 OK
-
-## 后续思路
-
-- 可继续把 `reduce` / `last` / `reverse` / `concat` / `to-list` / `to-set`
-  等也加入特化表；其中 `concat` / `reverse` 已有 native proc（`NativeListConcat`
-  / `NativeListReverse`），加到已有 proc 表即可。
-- 可以考虑把谓词（`list?`、`map?`、`number?`、`string?` …）在类型已知时直接折叠成
-  `true` / `false`，进一步帮 WASM / JS codegen 消冗余分支。
-- 未来 `&set:map` 如果单独实现，即可补齐 `("map", Set(_))` 分支。

package/editing-history/2026-04-17-0135-monomorphize-includes-reverse.md

@@ -1,31 +0,0 @@
-# Monomorphize `includes?` and `reverse`
-
-## 背景
-
-继 `map` / `filter` 之后，继续扩展 `try_specialize_polymorphic_call`：
-
-- `includes?` 原实现（calcit-core.cirru L3228）有 5 条 `if` 分支
-  （`nil?` / `list?` / `map?` / `set?` / `string?` fallback `.includes?`）。
-- `reverse` 实际上在 runtime 就是 `&list:reverse` 的别名，但以前每次调用还是要
-  经过一层 Calcit user-def 间接。
-
-## 改动
-
-在 `src/runner/preprocess/mod.rs` 的 proc 特化表中追加：
-
-```text
-("includes?", T::List(_))   -> NativeListIncludes
-("includes?", T::Map(_, _)) -> NativeMapIncludes
-("includes?", T::Set(_))    -> NativeSetIncludes
-("includes?", T::String)    -> NativeStrIncludes
-("reverse",   T::List(_))   -> NativeListReverse
-```
-
-`concat` 因为是变长参数 defn，暂不在这里处理；后续可以在 preprocess 阶段
-把已知都是 list 的 `(concat a b)` 展开为 `(&list:concat a b)` 的折叠形式。
-
-## 验证
-
-- `cargo fmt && cargo clippy --release -- -D warnings` ✓
-- `cargo test --release` ✓
-- `yarn check-all` ✓