@calcit/procs 0.12.55 → 0.12.57

package/RFCs/07-31-unsafe-coerce-driven-static-type-boundary-plan.md

@@ -0,0 +1,170 @@
+# RFC: `unsafe-coerce` 驱动的动态边界治理与静态类型强化计划
+
+状态：Draft
+日期：2026-07-31
+关联：`07-26-static-semantic-analysis-rfc.md`、`07-08-ffi-features-and-js-object-type-rfc.md`、`06-01-generic-binding-unification-rfc.md`
+
+## 1. 现状与目标
+
+我们将本阶段主目标聚焦在类型边界治理，而不是单纯推进 WASM 后端。
+针对 FFI（特别是 JS object）和外部大树形结构中大量动态值的问题，`unsafe-coerce` 要成为“静态分析可利用的类型入口点”，降低 `:dynamic` 退化。
+
+目标如下：
+
+- 让动态边界明确化：能指出哪些值是故意进入静态盲区，哪些是可治理缺口；
+- 提升静态可用信息：`unsafe-coerce` 后的类型关系要能在后续分析中被持续传播；
+- 降低告警噪音：减少因隐式动态而产生的误报，转而给出可执行的收紧建议。
+
+## 2. 问题定义
+
+当前主要痛点是三类：
+
+1. 外部输入（JS Object、外部树形数据）一旦进入，会被频繁打散成 `:dynamic`；
+2. `unsafe-coerce` 当前只附加声明类型，不转换值，也不提供运行时校验，静态分析无法区分“推导所得”与“用户信任声明”；
+3. 未通过显式边界收敛的动态传播，会导致高阶函数、容器、回调、trait 调用处丧失可验证关系。
+
+## 3. 设计思路
+
+我们将类型边界分为五档，贯穿检查与诊断链路：
+
+- `sealed-boundary`：明确的外部边界，需经过显式操作收窄；
+- `trusted`：`unsafe-coerce` 给出的用户信任声明，可传播但不视为运行时证明；
+- `validated`：由未来的实际校验操作建立的证据；
+- `unvalidated`：未经过转换但可继续跟踪的弱上下文；
+- `dynamic`：有意接受的动态盲区（可选 opt-in）。
+
+`unsafe-coerce` 必须具备两个产出：
+
+- 运行时行为：保持原值不变，不承诺验证；
+- 静态元信息：来源类型、声明目标类型、边界位置和 `trusted` 置信等级。
+
+实际完成运行时验证的能力应使用独立操作，并把置信等级提升为 `validated`，不能由 `unsafe-coerce` 冒充。
+
+## 4. 规范草案
+
+### 4.1 `unsafe-coerce` 的静态签名
+
+`unsafe-coerce` 调用应显式携带目标类型表达式，并在静态树或旁路分析元数据中记录：
+
+- `from-type`：调用点推断来源；
+- `to-type`：目标类型表达式；
+- `confidence`：固定为 `trusted`，不可标为 `validated`；
+- `evidence`：字段集合、泛型约束、变体等。
+
+示例：
+
+```cirru
+unsafe-coerce user-json :js-object
+unsafe-coerce user-json (:: :record User)
+unsafe-coerce tree-data (:: :list (:: :ref TreeNode))
+```
+
+### 4.2 结构化构造的类型加强策略（enum / struct）
+
+当调用头能够静态确认就是某个 `defstruct` 或 `defenum` 定义时，类型收敛可走“无缝构造”策略，减少 `::` / `%::` / `%{}` 的显式写法。普通 record 实例或 enum tuple 即使携带相同类型信息，也不得被当作构造器：
+
+- `enum`：在可推断为 enum 的位置，允许直接写 `Result :ok value`，由类型驱动 rewrite 成 `%:: Result :ok value`；
+- `struct`：在可推断为结构体的上下文，允许按字段对写 `Person :name |Alice :age 20`，并在类型上下文中改写为 `%{} Person :name |Alice :age 20` 的有序结构构造；
+- 规则约束仍保留：
+  - `struct` 必须是偶数个参数，按 key/value 成对出现；
+  - 字段不能重复；非 `:optional` 字段不能缺失；
+  - `enum` 的 tag 与 payload 必须匹配该 enum 的 variant；
+  - 任何 key 不在目标 struct 字段中的，回退到原有调用并给出 warning。
+
+示例：
+
+```cirru
+let
+    maybe-ok $ Result :ok 1
+    person $ Person :name |Alice :age 20
+  ...
+```
+
+负向示例（应保持原样并给 warning）：
+
+```cirru
+Person :name |Alice :age
+Result
+Result :bad 1
+Person :email |x
+Result ok 1
+kitty .rename |LagopusB
+```
+
+说明：
+
+- `Person :email |x`：字段不在结构定义中 → 回退并 warning；
+- `Person :name |Alice :age`：奇数参数 → 回退并 warning；
+- `Result ok 1`：enum 首参不是 tag（需 `:ok`）→ 回退并 warning；
+- `kitty .rename |LagopusB`：记录/结构方法调用不能被误判为构造调用。
+
+### 4.3 动态边界的使用规则
+
+1. 来自 FFI/主机接口的值默认进入 `sealed-boundary`；
+2. 若值要进入“纯 Calcit 计算路径”，必须通过 `unsafe-coerce` 进入可信声明类型，或通过实际校验操作进入已验证类型；
+3. 对容器与回调关系，`unsafe-coerce` 后应尽量保留内含关系（如 `:: :list T`、`:: :fn` 的参数/返回关联）；
+4. 对于无法构建精确信息的对象（如完全开放结构），允许 `:dynamic`，但必须记录“故意动态”标签与边界位置。
+
+### 4.4 与现有警告体系对齐
+
+- 引入/保留告警码：
+  - `W_SEALED_BOUNDARY_PASS`
+  - `W_MISSING_COERCE`
+  - `W_COERCE_COVERAGE_GAP`
+  - `W_DYNAMIC_EXIT`
+- `unsafe-coerce` 使用不足的动态传播点应由 `W_MISSING_COERCE` 定位，并给出可替换的目标类型示例；
+- `unsafe-coerce` 后仍不能稳定推断的情况，转为 `W_COERCE_COVERAGE_GAP` 并输出缺失字段/参数位置。
+
+### 4.5 与函数签名协同
+
+`unsafe-coerce` 不是为了替代 schema，而是使 schema 可恢复：
+
+- 大树节点进入列表/record 时，优先映射为命名结构体或 enum；
+- 回调参数在边界后保持 `:fn` 的关系（arg/return / generics / where）；
+- 若同一结构反复出现，鼓励提升为 `defstruct` + `:where` + 类型参数，减少重复 `:dynamic`。
+
+## 5. 实施路线
+
+### Phase 1（1~2 周）：把边界变可见
+
+- 明确 `unsafe-coerce` 在静态元数据中的记录模型，并保证 local 场景不会擦除边界节点；
+- 增加 `sealed-boundary` / `trusted` / `validated` / `unvalidated` / `dynamic` 标签在诊断中可见；
+- 在 `type-at` 与 `check-types` 输出中显示 `unsafe-coerce` evidence 链路；
+- 增加 `unsafe-coerce` 相关正向用例：JS Object → 记录/列表/enum。
+
+### Phase 2（2~3 周）：增强 `unsafe-coerce` 的传播能力
+
+- 在 container / fn / struct / enum 场景保留内含关系；
+- 增强跨文件、跨 def 的类型传播，支持大树结构递归字段推断；
+- 给 FFI 边界添加可执行的“首入场 unsafe-coerce 指南”（必须声明哪些层级，以及哪些位置需要真实校验）。
+
+### Phase 3（1~2 周）：治理现有动态盲区
+
+- 统计 `:dynamic` 产生原因：未转换、边界故意、兼容旧行为；
+- 逐步把“可修复” `:dynamic` 转为结构化 `unsafe-coerce` 或真实校验，保留“故意动态”最小集合；
+- 在 `analyze weak-types` 中增加类型边界报告：按定义、路径、优先级排序。
+
+## 6. 验收指标（建议）
+
+1. 关键 FFI 边界进入非纯路径时，`type-at` 能标出 `sealed-boundary`；
+2. 对树形/树状 JSON 数据，核心字段至少一层以上可从 `:dynamic` 收窄；
+3. 同一入口内的未转换动态访问点告警下降且可定位；
+4. 新增样例在 `check-types` 下可通过，不产生“类型丢失无法解释”的模糊告警。
+
+## 7. 风险与缓解
+
+- 风险：`unsafe-coerce` 过度强约束导致现有生态迁移成本上升。
+  缓解：保持 warning-first，逐步收紧。
+- 风险：分析时间上升。
+  缓解：对 `unsafe-coerce` evidence 做缓存并只在必要路径传播。
+- 风险：FFI 数据本身不稳定结构导致验证失败。
+  缓解：支持“部分声明 + `:dynamic` fallback”，让用户明确知道保留了什么边界。
+
+## 8. 依赖关系
+
+优先参考并复用：
+
+- `06-01-generic-binding-unification-rfc.md`
+- `07-26-static-semantic-analysis-rfc.md`
+- `07-08-ffi-features-and-js-object-type-rfc.md`
+- 现有类型诊断体系与 `analyze weak-types` 输出规范

package/build.rs

@@ -107,6 +107,41 @@ pub struct Snapshot {
   pub files: HashMap<String, FileInSnapShot>,
 }
 
+fn parse_snapshot_entry(data: Edn) -> Result<SnapshotEntry, String> {
+  let map = data.view_map().map_err(|e| format!("entry must be a map: {e}"))?;
+  let ns_def = |key: &str| match map.get_or_nil(key) {
+    Edn::Str(text) | Edn::Symbol(text) => Ok(text.to_string()),
+    other => Err(format!(
+      "entry `:{key}` must be a namespace/definition string or symbol, got {other:?}"
+    )),
+  };
+  let mode = match map.get_or_nil("mode") {
+    Edn::Tag(tag) if tag.ref_str() == "native" => SnapshotRunMode::Native,
+    Edn::Tag(tag) if tag.ref_str() == "js" => SnapshotRunMode::Js,
+    Edn::Str(text) | Edn::Symbol(text) if text.trim_start_matches(':') == "native" => SnapshotRunMode::Native,
+    Edn::Str(text) | Edn::Symbol(text) if text.trim_start_matches(':') == "js" => SnapshotRunMode::Js,
+    other => return Err(format!("entry `:mode` must be :native or :js, got {other:?}")),
+  };
+  Ok(SnapshotEntry {
+    mode,
+    init_fn: ns_def("init-fn")?,
+    reload_fn: ns_def("reload-fn")?,
+    description: from_edn(map.get_or_nil("description")).map_err(|e| format!("entry `:description`: {e}"))?,
+    modules: from_edn(map.get_or_nil("modules")).map_err(|e| format!("entry `:modules`: {e}"))?,
+    type_slots: from_edn(map.get_or_nil("type-slots")).map_err(|e| format!("entry `:type-slots`: {e}"))?,
+  })
+}
+
+fn parse_entries(data: Edn) -> Result<HashMap<String, SnapshotEntry>, String> {
+  let map = data.view_map().map_err(|e| format!("entries must be a map: {e}"))?;
+  let mut entries = HashMap::with_capacity(map.0.len());
+  for (name, value) in map.0 {
+    let name: String = from_edn(name).map_err(|e| format!("invalid entry name: {e}"))?;
+    entries.insert(name, parse_snapshot_entry(value)?);
+  }
+  Ok(entries)
+}
+
 fn format_edn_preview(value: &Edn) -> String {
   let raw = cirru_edn::format(value, true).unwrap_or_else(|_| format!("{value:?}"));
   const LIMIT: usize = 220;
@@ -479,8 +514,7 @@ fn main() {
       Some(from_edn::<LegacySnapshotConfigs>(value).unwrap_or_else(|e| panic!("failed to parse calcit-core legacy `:configs`: {e}")))
     }
   };
-  let mut entries: HashMap<String, SnapshotEntry> =
-    from_edn(data.get_or_nil("entries")).unwrap_or_else(|e| panic!("failed to parse calcit-core `:entries`: {e}"));
+  let mut entries = parse_entries(data.get_or_nil("entries")).unwrap_or_else(|e| panic!("failed to parse calcit-core `:entries`: {e}"));
   if let Some(configs) = &legacy_configs {
     entries.insert(
       "default".to_owned(),

package/editing-history/202607310224-strengthen-namespace-import-diagnostics.md

@@ -0,0 +1,23 @@
+# Strengthen namespace import diagnostics
+
+## Summary
+
+- Replaced namespace/import parser panics and silent fallbacks with contextual errors for malformed namespace forms, short rules, invalid rule kinds, and invalid node shapes.
+- Added one shared import-rule validator for program loading and `cr edit add-import` / `cr edit imports`, so invalid edits are rejected before the snapshot is saved.
+- Detect duplicate local bindings across rules and repeated `:refer` definitions within one rule instead of silently overwriting the earlier import.
+- Preserved legacy `(:ns namespace)` compatibility while validating supported `:require` structures.
+- Clarified that `call-graph --show-unused` reports definitions unreachable from the selected entry, not proven dead code or unused import declarations.
+- Kept unused-definition analysis independent from `--max-depth`, preventing display truncation from producing false dead-code reports.
+- Documented validation behavior, atomic edits, dead-code analysis limits, and the relevant CLI workflow.
+
+## Validation
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-all`
+- `yarn check-agent-interface` (12/12 scenarios)
+- `cr docs check-md docs/features/imports.md --entry calcit/test.cirru` (4/4 blocks)
+- Isolated CLI regressions confirming malformed and duplicate imports are rejected without changing the snapshot.
+- Compared `call-graph --show-unused` with unlimited depth and `--max-depth 1`; unused-definition results are identical.

package/editing-history/202607311940-strengthen-unsafe-coerce-boundaries.md

@@ -0,0 +1,20 @@
+# Strengthen unsafe-coerce boundaries
+
+## Summary
+
+- Kept `unsafe-coerce` visible in preprocessed expressions instead of mutating the source local's type globally, preserving a stable boundary node for later static evidence reporting.
+- Added type-directed shorthand construction for confirmed `defstruct` and `defenum` definitions while preventing record and enum tuple instances from being treated as constructors.
+- Validated shorthand struct fields for pair shape, membership, duplication, required-field coverage, and statically known value type mismatches.
+- Reused typed record and enum constructor nodes so native, JavaScript, and WASM backends receive their existing canonical forms.
+- Documented the boundary model, distinguishing trusted `unsafe-coerce` declarations from future runtime-validated evidence.
+- Added positive and negative preprocessing coverage for constructor rewrites, invalid variants, malformed fields, method syntax, and instance/prototype separation.
+
+## Validation
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-agent-interface` (12/12 scenarios)
+- `yarn check-all` (native, JavaScript, and WASM checks passed)
+- Current debug `cr --check-only` against `/Users/jon.chen/repo/respo/respo/calcit.cirru`

package/editing-history/202608010103-warn-on-duplicate-imports.md

@@ -0,0 +1,18 @@
+# Warn on duplicate imports
+
+- Changed duplicate namespace import bindings from validation errors to recoverable warnings on stderr.
+- Preserved the existing last-rule-wins behavior so duplicate aliases and repeated `:refer` entries do not stop program execution.
+- Kept malformed import structures, invalid rule kinds, and invalid node shapes as errors.
+- Updated CLI editing to save valid duplicate imports after displaying the warning.
+- Added tests for warnings and last-rule-wins resolution, plus an isolated CLI/runtime regression proving execution continues.
+- Updated import documentation to distinguish recoverable duplicate bindings from malformed rules.
+
+## Validation
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-all`
+- `yarn check-agent-interface` (12/12 scenarios)
+- `cr docs check-md docs/features/imports.md --entry calcit/test.cirru`

package/editing-history/202608010111-release-0.12.56.md

@@ -0,0 +1,15 @@
+# Release 0.12.56
+
+## Summary
+
+- Bump the Calcit Rust crate and npm package versions from `0.12.55` to `0.12.56`.
+- Refresh the workspace lockfile so package metadata remains consistent.
+
+## Validation
+
+- `cargo fmt --check`
+- `cargo clippy -- -D warnings`
+- `yarn compile`
+- `cargo test`
+- `yarn check-all`
+- `yarn check-agent-interface`

package/editing-history/202608011654-library-quality-gates.md

@@ -0,0 +1,23 @@
+# Library quality gates and format advisories
+
+## Summary
+
+- Add a dedicated Calcit library/module acceptance guide covering Snapshot canonicalization, entries, type slots, weak-type baselines, examples, Markdown checks, entry/backend validation, call-graph limits, consumer regression, and CI evidence.
+- Refresh the project upgrade guide for once-by-default execution, entry modes, unified `:entries`, per-entry type slots, canonical `:dynamic`, and current static-analysis commands.
+- Extend `cr edit format` with recoverable advisories for legacy `:configs`, the `compact.cirru` filename, legacy `:any`, and unresolved dynamic type debt.
+- Keep formatting non-blocking for quality debt and direct users to `check-types` / `weak-types` for semantic paths and recommendations.
+
+## Validation
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- focused `cr` format advisory unit tests
+- `cargo test`
+- `yarn compile`
+- `yarn check-all`
+- `yarn check-agent-interface`
+- `cr docs graph check`
+- `cr docs check-md docs/run/library-quality.md`
+- `cr docs check-md docs/run/upgrade.md`
+- legacy config and filename formatting on temporary Snapshots
+- Respo consumer regression on a temporary Snapshot: format, config show, weak-types summary, and `--check-only`

package/editing-history/202608011759-issue-routing-in-agent-guide.md

@@ -0,0 +1,17 @@
+# Route discovered issues to their owning repository
+
+## Summary
+
+- Add an Agent-guide rule requiring reproducible Calcit language, runtime, compiler, and CLI issues to be filed with their maintenance repository.
+- Route module and library defects from their resolved local path to the library's own GitHub repository, rather than reporting them to the consuming project or Calcit core by default.
+- Document explicit cross-repository issue creation with `gh issue create --repo OWNER/REPO`, target verification with `gh repo view`, evidence requirements, and safe handling of sensitive reproduction data.
+
+## Validation
+
+- Confirmed `gh issue create --help` exposes `--repo [HOST/]OWNER/REPO` for selecting another repository.
+- Confirmed the current GitHub CLI authentication can query the non-current `calcit-lang/setup-cr` repository.
+- `cargo build --bin cr`
+- `cargo test --bin cr agents_docs_default_to_the_version_matched_embedded_guide`
+- `./target/debug/cr docs check-md docs/CalcitAgent.md --entry calcit/test.cirru --failures-only`
+- `./target/debug/cr docs graph check`
+- `git diff --check`

package/editing-history/202608011833-schema-type-symbols.md

@@ -0,0 +1,20 @@
+# Canonical schema types use quoted symbols
+
+## Summary
+
+- Keep legacy lowercase type tags load-compatible, while making quoted symbols such as `'String`, `'List`, `'Fn`, and `'Dynamic` the canonical schema serialization.
+- Make `cr edit format` rewrite only recognized type positions in schemas, hints, assertions, coercions, structs, and enums; ordinary tag data remains unchanged.
+- Migrate repository Snapshots, type-query/IR/agent-interface output, build-time core Snapshot loading, and primary type documentation.
+
+## Validation
+
+- `cargo fmt`
+- `cargo test`
+- `cargo clippy -- -D warnings`
+- `yarn compile`
+- `yarn check-all`
+- `yarn check-agent-interface`
+- `cr docs check-md docs/features/static-analysis.md --entry calcit/test.cirru --failures-only`
+- `cr docs check-md docs/CalcitAgent.md --entry calcit/test.cirru --failures-only`
+- `cr docs graph check`
+- formatted every valid repository Snapshot with `cr edit format`, then `cr calcit/test.cirru --check-only`

package/editing-history/202608011852-wasm-dynamic-string-tag.md

@@ -0,0 +1,7 @@
+# WASM dynamic string tag
+
+- Schema type migration removed legacy type tags from program data, which can shift WASM's program-local tag indices.
+- The Node.js WASM test host must not assume that the `string` type tag always has index 34.
+- Export the generated module's actual string tag as `__string_tag` and use that value when the host validates or allocates strings.
+- Keep the test host compatible with older generated modules by recovering the tag from their static string pool when the export is absent.
+- Regression command: `cargo build --bin cr-wasm && CR_WASM_BIN=./target/debug/cr-wasm bash scripts/test-wasm.sh`.

package/editing-history/202608011908-consolidate-history.md

@@ -0,0 +1,6 @@
+# Consolidate historical editing notes
+
+- Replaced 142 individual notes from June 2026 and earlier with a compact topic index.
+- Retained all July–August notes for active maintenance context.
+- The removed notes remain recoverable through Git history; `editing-history/README.md` documents the retention rule.
+- Verification: reviewed the tracked path set and checked the resulting Git diff.

package/editing-history/202608012022-consolidate-cli-and-test-duplication.md

@@ -0,0 +1,28 @@
+# Consolidate CLI and test duplication
+
+## Summary
+
+- Introduced a typed `TreeOperation` model and shared cursor path transforms so edit, tree, and cursor commands use one implementation for structural mutations.
+- Reused one staged-file abstraction for atomic cursor writes and edit transactions, including permission preservation, sync, commit, and cleanup behavior.
+- Consolidated query result collection/rendering and type-coverage scope traversal without changing their JSON envelopes or diagnostics.
+- Added one test-only temporary project fixture shared by edit, cursor, and query tests.
+- Replaced eight identical Calcit test-local `log-title` definitions with `util.core/log-title`, keeping each standalone snapshot loadable through its module configuration.
+- Removed the misspelled `test-gynienic.cirru` snapshot because the typed `test-hygienic.cirru` suite is a strict superset, and removed the identical `test-cond` runtime case from the macro suite.
+- Made the remaining `case-default` macroexpansion assertion deterministic by resetting the gensym counter before checking the generated symbol.
+
+## Review notes
+
+- Kept repeated `main!` and `reload!` definitions because they are snapshot entry points rather than interchangeable helpers.
+- Kept similarly named macro, native, JS, and WASM tests when they exercise different expansion or backend behavior.
+- The resulting tracked diff removes more code than it adds while retaining the command boundaries and test coverage.
+
+## Validation
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-agent-interface` (12/12 scenarios)
+- `yarn check-all` (native, JS, and WASM)
+- Standalone native runs for the updated Calcit snapshots, including `test-cond.cirru`, `test-macro.cirru`, and `test-hygienic.cirru`
+- Real-project Respo regression with JSON definition query and summary-only type-coverage analysis

package/editing-history/202608012123-review-follow-up.md

@@ -0,0 +1,18 @@
+# Review follow-up for CLI consolidation
+
+## Summary
+
+- Updated staged-file rewriting to open the temporary file with write access, truncate it, write through the same handle, and then sync it. This keeps `sync_all` valid on Windows.
+- Reject symbolic-link destinations before staging so an atomic rename cannot silently replace the link while preserving permissions from its target.
+- Avoid copying every definition tree during whole-project search; only a subtree selected by `--start-path` remains owned.
+- Corrected cursor feedback so replace, swap, unwrap, and wrap report an unaffected cursor when their path did not change.
+
+## Tests
+
+- Added staged write/commit coverage and a Unix symbolic-link rejection test.
+- Added cursor feedback assertions for unrelated paths and single-child unwraps.
+
+## Review disposition
+
+- Kept the existing parent-context preview for `query search-expr`; it predates this refactor and is intentional shared search presentation rather than a regression.
+- Deferred directory `fsync` after rename: it is a larger crash-durability policy decision, especially for multi-file commits, and is not needed to correct the current atomic rename behavior.

package/editing-history/202608012320-release-0.12.57.md

@@ -0,0 +1,5 @@
+# Release 0.12.57
+
+- Release the merged CLI mutation, atomic staging, and test deduplication work from PR #284.
+- Include the follow-up fixes for Windows staged-file synchronization, symlink destinations, query cloning, and cursor feedback.
+- Synchronize the Rust crate and npm package versions, then refresh the workspace lockfile before publishing.

package/editing-history/ARCHIVE.md

@@ -0,0 +1,15 @@
+# Consolidated history through June 2026
+
+Detailed task notes before July 2026 were consolidated on 2026-08-01. Their
+full text remains recoverable from Git history; this file preserves the useful
+navigation layer.
+
+| Period | Durable themes |
+| --- | --- |
+| 2025–Feb 2026 | WASM/codegen groundwork, structural equality, diagnostics, core API documentation, and migration toward `defstruct`. |
+| Mar 2026 | Schema and type-annotation redesign: `hint-fn` migration, schema normalization/validation, generic type references, arity checks, and type-fail coverage. |
+| Apr 2026 | Records/enums, type narrowing and generic dispatch; the WASM runtime gained collections, strings, methods, host imports, and multi-module tests. |
+| May–Jun 2026 | Weak-type analysis, data-definition bounds, markdown checking, compiled-runtime backfill, scoped type slots, effects graph, and Agent/CLI documentation. |
+
+For current behavior, prefer `docs/`, tests, and the retained July–August notes
+over this summary.

package/editing-history/README.md

@@ -0,0 +1,21 @@
+# Editing history
+
+This directory keeps short, task-specific notes that help with nearby follow-up
+work. It is not a second changelog: exact prior notes remain available from Git
+history after they leave this directory.
+
+## Retention
+
+- Keep individual notes for the current development window (normally the most
+  recent 45 days).
+- Periodically replace older clusters with a concise topic summary in
+  [ARCHIVE.md](ARCHIVE.md), then remove their individual files.
+- Each code commit still adds one timestamped note, but it should capture only
+  durable context: the reason for the change, compatibility constraints, and
+  the relevant verification command.
+
+To recover a removed note, search the repository history, for example:
+
+```bash
+git log --all -- editing-history/
+```

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.55",
+    "version": "0.12.57",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.7.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.55",
+  "version": "0.12.57",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.7.0",

package/editing-history/2026-02-13-1841-trait-origin-structural-eq.md

@@ -1,91 +0,0 @@
-# 202602131841 trait origin 匹配与结构化 trait 相等性
-
-## 背景
-
-本次提交延续了动态方法告警收敛与 trait 分发可靠性改进。
-评审中提出的核心问题是：trait 分发不应只依赖 trait 名称匹配。
-`impl` 记录本身已经携带了 trait 的 origin 元数据，因此匹配应直接基于 origin。
-
-## 目标
-
-1. 让 `&trait-call` 按 trait origin 相等性选择 impl，而不是按名称字符串匹配。
-2. 让 trait/impl 的相等语义与上述运行时选择模型一致。
-3. 在尽量保持兼容的前提下，提高歧义/重名场景下的正确性。
-4. 保持现有优先级规则不变（用户 impl：后者覆盖前者；内建 impl：前者优先）。
-
-## 思考过程
-
-### 为什么 name-only 匹配不够
-
-- 仅按名称匹配会把“同名但结构不同”的 trait 混为一类。
-- 运行时已有 `CalcitImpl.origin: Option<Arc<CalcitTrait>>`，若忽略它会浪费已有语义信息。
-- 使用显式 `&trait-call` 时，调用方预期的是“精确 trait 命中”，而非按名字近似匹配。
-
-### 分发策略决定
-
-在 `trait_call` 中：
-
-- 旧逻辑：`imp.trait_name()` 与 `trait_def.name` 比较。
-- 新逻辑：`imp.origin()` 与目标 trait 直接通过 `Eq` 比较。
-
-该方案改动小、语义清晰，并与当前运行时模型一致，不引入额外解析复杂度。
-
-### Eq/Hash 一致性
-
-当分发切换到 origin 相等后，`CalcitTrait` 的相等语义就不能继续只看 `name`。
-
-因此将 `CalcitTrait` 的 Eq/Hash 升级为结构化比较，包含：
-
-- trait 名称
-- 方法名列表
-- 方法类型签名
-- requires（依赖 trait）
-- 默认实现槽位形状（每个位置是 `Some` 还是 `None`）
-
-关于默认实现：
-
-- 默认函数体（`CalcitFn`）不做深比较/深哈希，因为 `CalcitFn` 当前不提供完整 Eq/Hash。
-- 这里只比较默认槽位可用性形状，以保证 Eq/Hash 契约一致，同时提升结构判断准确性。
-
-## 文件级改动
-
-### 运行时分发与文档
-
-- `src/builtins/meta.rs`
-  - `trait_call` 改为按 `impl.origin` 相等匹配。
-  - 同步更新函数附近注释，确保文档与实现一致。
-
-### impl 相等性
-
-- `src/calcit/calcit_impl.rs`
-  - `PartialEq` 改为直接比较 `origin`（不再只比较 `origin.name`）。
-
-### trait 相等性与哈希语义
-
-- `src/calcit/calcit_trait.rs`
-  - `PartialEq` 从 name-only 改为结构化比较。
-  - `Hash` 同步到相同结构维度。
-  - 增加注释，说明默认函数比较策略。
-
-### 相关一致性修正（同一工作区变更）
-
-- `src/runner/preprocess.rs`
-  - 修复重命名后的测试守卫符号残留（`DynTraitCheckGuard` -> `WarnDynMethodGuard`）。
-
-## 验证
-
-- `cargo fmt`
-- `cargo test -q`
-  - 结果：当前工作区下测试全部通过。
-
-## 兼容性与风险
-
-- 该行为变化是有意为之：同名但结构不同的 trait 不再被视为相等。
-- 默认函数体差异仍不纳入 Eq/Hash。
-- 方法分发优先级规则保持不变。
-
-## 后续可选项
-
-1. 如有需要，可补强默认实现身份比较（例如优先比较 def ref）。
-2. 增加“同名不同结构 trait”相等性的显式测试用例。
-3. 继续收敛 `warn-dyn-method` 全量运行中的剩余动态调用告警。

package/editing-history/2026-02-14-2050-js-codegen-recursion-tag-migration.md

@@ -1,39 +0,0 @@
-# 2026-02-14 20:50 JS codegen recursion + tag migration
-
-## 背景
-
-在 trait/macro 改进后，继续针对 JavaScript 编译目标做性能与可维护性优化。
-
-## 本次改动
-
-1. 参数个数报错模板统一
-
-- 在 runtime 新增 `_args_fewer_throw` / `_args_between_throw`，保留 `_args_throw`。
-- emitter 中 `too few/too many` 模板改为调用统一 helper，错误信息继续携带期望与实际参数个数。
-
-2. rest 参数处理优化
-
-- 对 `&` rest 参数，仅在函数体实际引用时才注入 `arrayToList` 转换，避免不必要转换。
-- 修复符号引用检测边界：`contains_symbol` 增加 `Calcit::Local` 分支。
-
-3. tail recursion 模板优化
-
-- watchdog 从每轮检查改为周期检查（`(times & 1023) === 0` 时再判断上限）。
-- 对无 rest/optional 的固定参数函数，recur 回填改为索引赋值（`arg = ret.args[i]`），减少解构开销。
-
-4. tag 初始化一次迁移
-
-- runtime 新增 `init_tags` 与全局 tag 缓存。
-- emitter 统一改为 `const _t_ = init_tags([...])` / `$clt.init_tags([...])`。
-- 移除每模块内联 `forEach + newTag` 初始化模板。
-- 修复 `calcit.core` 目标缺失导入，补上 `init_tags` import。
-
-## 验证
-
-- `yarn check-all` 通过。
-- 额外执行了 JS 微基准（`test-recursion.main/test_loop`）用于观察 recursion 模板优化影响。
-
-## 经验点
-
-- JS 生成模板优化要先保证语义完整，再做结构性收敛（helper 化/去重复）。
-- 对 codegen 的性能优化，建议配套微基准，并与 baseline 做同脚本对比。