@calcit/procs 0.12.56 → 0.12.57

package/editing-history/2026-03-07-1959-schema-def-kind-arity-validation.md

@@ -1,96 +0,0 @@
-# Schema vs Definition Kind/Arity Validation
-
-## Summary
-
-Added structural validation that compares a definition's code form against its schema declaration. This catch mismatches between declared schema metadata (`:kind`, arg count, rest param) and the actual `defn`/`defmacro` code at analysis time.
-
-## Key Changes
-
-### `src/calcit/type_annotation.rs`
-
-1. **Added `SchemaKind` enum** (`pub enum SchemaKind { Fn, Macro }`) — distinguishes `:kind :fn` from `:kind :macro` schemas.
-
-2. **Extended `CalcitFnTypeAnnotation`** with two new fields:
-   - `pub fn_kind: SchemaKind` — schema's declared kind (fn/macro).
-   - `pub rest_type: Option<Arc<CalcitTypeAnnotation>>` — schema's `:rest` type, if present.
-
-3. **`parse_fn_schema_from_edn`** — now reads `:kind :macro` → `SchemaKind::Macro` and `:rest` → `rest_type` from the EDN map.
-
-4. **`to_schema_edn`** — now serializes `fn_kind` (`fn`/`macro`) and `rest_type` (`:rest` key in the output map). Previously always emitted `:kind :fn` and omitted `:rest`.
-
-5. **All `CalcitFnTypeAnnotation` construction sites** updated to add `fn_kind: SchemaKind::Fn, rest_type: None` defaults (7 total).
-
-6. **`substitute_type_vars`** also propagates `fn_kind` and substitutes `rest_type`.
-
-### `src/calcit.rs`
-
-- `SchemaKind` added to the `pub use type_annotation::{ ... }` re-export.
-
-### `src/bin/cr.rs`
-
-1. **`SchemaKind` imported** in the `use calcit::calcit::{...}` block.
-
-2. **`TypeCoverageRow` struct** gained `schema_issues: Vec<String>` field — carries kind/arity mismatch warnings per definition.
-
-3. **`validate_def_vs_schema(ns, def_name, code, schema) -> Vec<String>`** — new function:
-   - `&runtime-inplementation` leaf → skip (builtin proc/syntax).
-   - Schema not `CalcitTypeAnnotation::Fn` → skip.
-   - Code head not `defn`/`defmacro` → skip.
-   - Schema `:kind :fn` + code `defmacro` → error.
-   - Schema `:kind :macro` + code `defn` → error.
-   - Required arg count mismatch → error.
-   - `has_rest` mismatch (schema `:rest` vs code `&`) → error.
-
-4. **`analyze_param_arity(args: Option<&Cirru>) -> (usize, bool)`** — helper that counts required params and detects the `&` rest marker in a `defn`/`defmacro` args list.
-
-5. **`analyze_code_entry`** calls `validate_def_vs_schema` to populate `schema_issues` on each `TypeCoverageRow`.
-
-6. **`run_check_types` output loop** prints a `schema-issues:` section for rows with non-empty issues.
-
-7. **10 new unit tests** covering:
-   - `&runtime-inplementation` skip
-   - Correct defn/macro → no issues
-   - Kind mismatch (`:fn` vs `defmacro`, `:macro` vs `defn`)
-   - Arity mismatch
-   - Rest param mismatch
-   - `analyze_param_arity` basics
-8. **`CR_DEBUG_SCHEMA` debug flag** — when `CR_DEBUG_SCHEMA=1`, prints per-entry schema kind debug info to stderr during `analyze check-types`.
-
-### `src/runner/preprocess.rs`
-
-1. **Runtime/preprocess enforcement added** — schema-vs-definition structural checks now run while preprocessing `defn`/`defmacro`, not only in `analyze check-types`.
-2. **`validate_def_schema_during_preprocess(...)`** — mirrors the `check-types` validation for `:kind`, required arity, and `:rest`, and raises a hard `[Type Error]` during normal execution paths such as `yarn try-rs`.
-3. **Schema hints preserved** — preprocess still injects `hint-fn`, but now only after the definition passes structural schema validation.
-4. **2 new preprocess tests** covering arity mismatch and `:kind` mismatch at preprocess time.
-
-### `calcit/test-hygienic.cirru`
-
-- Updated existing test fixture schemas so they match actual code:
-  - `add-11` / `add-11-safe`: `:kind :macro`
-  - `add-2`: arg schema corrected from 2 params to 1
-
-### `src/snapshot.rs`
-
-- **`test_macro_schema_round_trip`** — verifies `schema_cirru_to_edn` + `parse_fn_schema_from_edn` + `normalize_schema_edn` preserve `SchemaKind::Macro` end-to-end.
-- **`test_macro_schema_full_file_round_trip`** — verifies full `CodeEntry` serialize (`From<&CodeEntry> for Edn`) → `cirru_edn::format` → `cirru_edn::parse` → `TryFrom<Edn> for CodeEntry` round-trip preserves `fn_kind: Macro`.
-
-## Validation Rule Summary
-
-| Schema `:kind` | Code form                 | Result          |
-| -------------- | ------------------------- | --------------- |
-| `:fn`          | `defn`                    | ✓ ok            |
-| `:fn`          | `defmacro`                | ✗ kind mismatch |
-| `:macro`       | `defmacro`                | ✓ ok            |
-| `:macro`       | `defn`                    | ✗ kind mismatch |
-| any            | `&runtime-inplementation` | ✓ skip          |
-
-Arg count and rest param are checked independently of kind.
-
-## Notes
-
-- **`calcit.core` schemas require binary rebuild**: Schema edits to `src/cirru/calcit-core.cirru` do not take effect at runtime until the binary is rebuilt, because the core namespace is always loaded from the embedded `include_bytes!` snapshot produced by `build.rs`. Schema validation is most useful for user-defined namespaces.
-- **Normal execution now checks schemas too**: before this follow-up, schema-vs-def mismatches were only reported by `analyze check-types`; now they fail fast during normal preprocess/runtime startup as well.
-
-## Test Results
-
-All 125 tests pass (99 library + 26 binary), including 2 new snapshot round-trip tests and 2 new preprocess validation tests.

package/editing-history/2026-03-08-0031-schema-generics-quote-normalization.md

@@ -1,35 +0,0 @@
-# Schema Generics Quote Normalization
-
-## Summary
-
-Tightened schema loading so legacy generic symbols stored with embedded leading quotes now fail immediately, then normalized existing `calcit-core.cirru` schema generics from `''T`-style output to the correct `'T` source syntax.
-
-## Key Changes
-
-- `src/calcit/type_annotation.rs`
-  - Stopped serializing schema generics as `Edn::Symbol("'T")`.
-  - Now writes plain EDN symbols like `Edn::Symbol("T")`, which format back to source as `'T`.
-  - Keeps compatibility when parsing previously saved legacy symbols, but normalizes them to plain names.
-
-- `src/snapshot.rs`
-  - Added load-time rejection for legacy schema generic symbols carrying embedded leading quotes.
-  - Normalized schema EDN → Cirru conversion to go through format+parse so quoted symbols render correctly.
-  - Added regression tests for:
-    - single-quote round-trip,
-    - rejecting legacy quoted EDN symbols on load,
-    - rejecting `''T` on schema writes.
-
-- `build.rs`
-  - Added the same legacy-generic rejection during build-time loading of `src/cirru/calcit-core.cirru`, so bad schema data fails `yarn check-all` immediately.
-
-- `src/cirru/calcit-core.cirru`
-  - Replaced all legacy schema generic forms like `''T`, `''A`, `''K` with correct single-quoted forms.
-
-- `docs/CalcitAgent.md`
-  - Updated schema/type-annotation guidance to reflect schema-first top-level typing and correct generic syntax examples.
-
-## Validation
-
-- `cargo fmt`
-- `cargo test schema_ -- --nocapture`
-- `yarn check-all`

package/editing-history/2026-03-08-1905-schema-typeref-and-assert-migration.md

@@ -1,34 +0,0 @@
-# 本次修改记录
-
-## 主题
-
-- 完善 schema 类型系统：区分泛型变量与命名类型引用，支持 `'Result` 一类类型引用在 schema 中稳定往返。
-- 继续推进 schema-first 迁移：清理 `calcit-core` 与若干测试文件中的 `assert-type`，将约束收敛到 `:schema` 与局部 `hint-fn`。
-- 强化诊断：改进运行时参数个数错误与构建期 schema 解析报错，方便定位问题。
-
-## 主要改动
-
-### 1) Rust 侧类型系统收紧
-
-- 在 `src/calcit/type_annotation.rs` 中新增命名类型引用分支，并让解析、匹配、显示、序列化都感知泛型作用域。
-- `src/builtins/syntax.rs` 与 `src/builtins/records.rs` 改为按泛型上下文解析 schema，避免把命名类型误判成 type var。
-- `src/codegen/gen_ir.rs`、`src/snapshot.rs` 同步适配新 schema 结构与 round-trip 测试。
-
-### 2) schema / hint-fn 迁移
-
-- `src/cirru/calcit-core.cirru` 中移除剩余 `assert-type` 调用点，改为顶层 `:schema` 或局部 `hint-fn`。
-- `calcit/test.cirru`、`calcit/debug/check-args.cirru`、`calcit/test-fn.cirru`、`calcit/test-types.cirru` 改用更精细的函数签名与局部约束。
-- 修正函数类型直写 schema 的参数形式，统一使用 `([] ...)` 表达参数列表。
-
-### 3) 错误信息增强
-
-- `src/runner.rs` 在参数个数不匹配时生成结构化报错，而不是直接触发内部 panic。
-- `build.rs` 对 schema EDN 解析错误增加截断与整理，避免输出过长、难以定位。
-
-## 验证
-
-- `cargo fmt` 通过。
-- `cargo clippy -- -D warnings` 通过。
-- `yarn compile` 通过。
-- `cargo test` 通过。
-- `yarn check-all` 通过。

package/editing-history/2026-03-08-2033-schema-wrapper-migration.md

@@ -1,45 +0,0 @@
-# 2026-03-08 schema wrapper migration
-
-## Summary
-
-- 统一函数 schema 的 snapshot 输出格式，顶层改为 wrapped `:: :fn` / `:: :macro` 形式。
-- 修复 schema round-trip 中的类型信息丢失，确保嵌套函数类型与 `:rest` 在格式化后保持稳定。
-- 将 macro schema 的顶层格式统一迁移到 `:: :macro`，并让 formatter 在处理 `defmacro` 条目时自动纠正旧的 `fn` 标记。
-- 移除 legacy quote-wrapped schema normalization 与 legacy positional `fn` type annotation fallback，收紧到当前 schema-map 形式。
-- 更新 `deftrait` 文档与相关说明，避免继续传播旧写法。
-
-## Main changes
-
-### 1) 顶层 schema 输出统一
-
-- 在 `src/calcit/type_annotation.rs` 中补充顶层 wrapped schema 的解析与序列化逻辑。
-- 在 `src/snapshot.rs` 中让 `CodeEntry.schema` 写回 snapshot 时统一输出为 `:schema $ :: :fn ...` 或 `:schema $ :: :macro ...`。
-- 对 plain fn schema 去掉 wrapped payload 内冗余的 `:kind :fn`，但保留宏函数所需的 `:kind :macro`。
-
-### 2) macro schema 迁移与规范化
-
-- 扩展 parser / normalize 逻辑，使其同时接受 wrapped `fn` 与 wrapped `macro`。
-- 对 macro schema，序列化时省略冗余的 `:kind :macro` 与 `:return`，仅保留 `:args` 与可选 `:rest`。
-- 在 snapshot 读写路径中，根据代码头是否为 `defmacro` 自动纠正 schema kind。
-
-### 3) legacy fn syntax 收紧
-
-- 移除 legacy quote-wrapped schema normalization。
-- 拒绝 legacy quoted generic symbols。
-- 移除 legacy positional `fn` type annotation parsing fallback。
-- 迁移剩余 core trait 与测试注解到 schema-map `:: :fn {}` 形式。
-
-### 4) round-trip 与批量格式化
-
-- 修复 EDN 到 Calcit 的转换路径，补上 `Edn::Map` 的处理，避免嵌套 `fn` schema 的 hashmap payload 被吞掉后退化成 `:dynamic`。
-- 调整 schema 校验与 normalize 逻辑，使 wrapped 顶层 fn schema 与旧格式都能稳定读写。
-- 重新格式化了 `src/cirru/calcit-core.cirru`、`calcit/util.cirru`、`calcit/test-hygienic.cirru` 等兼容 snapshot 文件。
-
-## Validation
-
-- `cargo fmt`
-- `cargo clippy -- -D warnings`
-- `yarn compile`
-- `cargo test -q`
-- `cargo build -q`
-- `yarn check-all`

package/editing-history/2026-03-08-2315-late-schema-cleanup-and-warning-compat.md

@@ -1,27 +0,0 @@
-# 2026-03-08 late schema cleanup and warning compatibility
-
-## Summary
-
-- made snapshot schema loading strict for non-nil schemas, so malformed schema data no longer silently degrades to dynamic
-- normalized loaded schema maps so legacy string keys and string `:kind` values are converted into canonical tag-based schema maps
-- restored generic type variables in `src/cirru/calcit-core.cirru` where a previous migration had incorrectly replaced them with `:symbol`
-- cleaned the remaining mistaken `:symbol` placeholders in core collection schemas, keeping only the intentional `symbol?` runtime type check
-- fixed `calcit/test-generics.cirru` after a schema-formatting edit moved `assert-type id ...` into the `let` binding section
-- kept `ns/def` warning location reporting for embedded core snapshot loading
-- stopped legacy fn-schema warnings from firing on malformed nested `:: :fn` schema payloads parsed from `calcit-core.cirru`
-- used a conservative fallback to `DynFn` for malformed nested payloads, avoiding false-positive callback type warnings without re-editing Cirru syntax
-
-## Notes
-
-- `yarn check-all` passed after the generic-schema restoration and remaining `:symbol` cleanup passes
-- the `test-generics` fix resolves the runtime error `expected binding of a pair`
-- nested function schema payloads coming from Cirru snapshot EDN may currently collapse into malformed map payloads like `(:: :fn ({} (nil ...)))` or `(:: :fn ({}))`
-- those malformed payloads are lossy, so partially reconstructing arg/return types can introduce new static-analysis warnings
-- decoding the embedded binary core snapshot with per-entry owners is necessary to preserve precise warning locations such as `calcit.core/foo`
-
-## Validation
-
-- `cargo test -q malformed_nested_fn_schema`
-- `cargo build -q`
-- `target/debug/cr calcit/test.cirru -1`
-- `yarn check-all`

package/editing-history/2026-03-09-1753-schema-type-fail-tests.md

@@ -1,17 +0,0 @@
-# schema type-fail tests and error codes
-
-- 新增 `calcit/type-fail/` 下 schema 相关失败 fixture 的自动化测试，覆盖：
-  - `:args` required arity mismatch
-  - `:rest` presence mismatch
-  - `:kind` mismatch
-  - 基于 schema 的调用参数类型不匹配
-- 在 `src/bin/cr.rs` 中补充 fixture 加载 helper，并通过 `run_check_only()` / preprocess warning 断言行为。
-- 为类型/预处理相关告警补充 code：
-  - `W_FN_ARG_TYPE_MISMATCH`
-  - `W_PROC_ARG_TYPE_MISMATCH`
-  - `W_CORE_FN_ARG_TYPE_MISMATCH`
-  - `W_FN_RETURN_TYPE_MISMATCH`
-- 为 schema 定义不匹配错误补充 code：
-  - `E_SCHEMA_DEF_MISMATCH`
-- 为 `CalcitErr` 增加 `code` 字段和 `headline()`，让 CLI 输出可携带错误码。
-- 更新 `calcit/type-fail/README.md`，记录自动化测试与当前相关 code。

package/editing-history/2026-03-10-1040-edit-schema-primitive-tag-support.md

@@ -1,42 +0,0 @@
-# cr edit schema: support primitive type tag leaves
-
-## 背景
-
-`cr edit schema` 原来只接受 `:: :fn $ {}` 这样的函数 schema 或 `{}` map 形式。
-有些定义的类型本身就是简单原始类型（如 `:string`、`:number`），不是函数，需要直接用 tag 表达。
-
-## 新语法
-
-```bash
-cr edit schema 'respo.comp.space/style-space' --code 'quote :string'
-cr edit schema 'some.ns/my-val' --code 'quote :number'
-cr edit schema 'some.ns/my-flag' --code 'quote :bool'
-```
-
-接受的 primitive 类型 tag：`bool`, `number`, `string`, `symbol`, `tag`, `list`, `map`, `set`, `fn`, `tuple`, `ref`, `buffer`, `dynamic`, `unit`
-
-## 改动文件
-
-### `src/calcit/type_annotation.rs`
-
-- `builtin_tag_name` 改为 `pub(crate)`，供 snapshot 序列化侧调用。
-
-### `src/snapshot.rs`
-
-- 新增常量 `PRIMITIVE_SCHEMA_TAGS`：列出允许作为 leaf schema 的原始类型。
-- `validate_schema_for_write`：对 `Cirru::Leaf` 先检查是否在允许列表，允许则直接 Ok；否则给出提示信息。
-- `parse_loaded_schema_annotation`：新增对 `Edn::Tag` 的处理，返回对应 `CalcitTypeAnnotation`。
-- 两处 `CodeEntry::From` impl：`_ => Edn::Nil` 改为调用 `builtin_tag_name().map(Edn::tag)` 把原始类型 tag 正确序列化到快照。
-- 测试 `test_validate_schema_for_write`：更新为测试原始类型 leaf 通过、未知 leaf 拒绝。
-
-### `src/bin/cli_handlers/edit.rs`
-
-- `handle_schema`：`validate_schema_for_write` 通过后，若 `schema_payload` 是 `Cirru::Leaf`，用 `CalcitTypeAnnotation::from_tag_name` 直接设置 schema 并返回，不走函数 schema 解析路径。
-
-## 完整数据流（以 `:string` 为例）
-
-1. CLI 收到 quoted schema 输入 `--code 'quote :string'`，取出 payload 后得到 `Cirru::Leaf(":string")`
-2. `validate_schema_for_write` → `"string"` 在 `PRIMITIVE_SCHEMA_TAGS` → Ok
-3. `CalcitTypeAnnotation::from_tag_name("string")` → `CalcitTypeAnnotation::String`
-4. 写入快照 → `CodeEntry::From` 序列化为 `Edn::tag("string")`
-5. 读回快照 → `parse_loaded_schema_annotation(Edn::Tag("string"))` → `CalcitTypeAnnotation::String`

package/editing-history/2026-03-10-1754-ns-entry-snapshot-migration.md

@@ -1,66 +0,0 @@
-# 2026-0310-1754 — snapshot namespace entry migrate to NsEntry
-
-## 背景
-
-snapshot 里的 `:ns` 之前复用了 `CodeEntry` 结构，导致 namespace 也带着 `:schema` 和 `:examples` 字段，语义上并不合适，而且保存时经常只是写成 `(:schema nil)`。
-
-这次改动把 namespace 入口单独收敛到 `NsEntry`，同时保持读取旧 `CodeEntry` 写法的兼容性。
-
-## 核心改动
-
-### `src/snapshot.rs`
-
-- 新增 `NsEntry { doc, code }`
-- `FileInSnapShot.ns` 从 `CodeEntry` 改为 `NsEntry`
-- `RawFileInSnapShot.ns` 同步改为 `NsEntry`
-- 新增 `TryFrom<Edn> for NsEntry` 与 `From<NsEntry> for Edn`
-- 读取 snapshot 时，`ns` 只解析 `doc` 和 `code`，兼容旧 `CodeEntry` 形状并忽略 `schema/examples`
-- 移除 `validate_snapshot_schemas_for_write` 对 `ns.schema` 的校验
-- `gen_meta_ns`、`create_file_from_snippet` 等内部构造统一改为写 `NsEntry`
-
-### `build.rs`
-
-- 嵌入式 core snapshot 解析结构新增 `NsEntry`
-- build 阶段读取 `src/cirru/calcit-core.cirru` 时，`ns` 不再解析为 `CodeEntry`
-
-### `src/detailed_snapshot.rs`
-
-- 新增 `DetailedNsEntry { doc, code }`
-- `DetailedFileInSnapshot.ns` 从 `DetailedCodeEntry` 改为 `DetailedNsEntry`
-- 详细快照读取仍兼容旧 namespace record，只提取 `doc` 和 `code`
-
-### `src/bin/cr_sync.rs`
-
-- namespace change payload 从 `CodeEntry` 拆成 `SnapshotEntry::Ns(NsEntry)`
-- definition change payload 保持 `SnapshotEntry::Def(CodeEntry)`
-- detailed snapshot 写回时，namespace 统一序列化为 `NsEntry`
-
-### `src/bin/cli_handlers/edit.rs`
-
-- `edit add-ns` 创建新 namespace 时直接写入 `NsEntry`
-
-## 数据文件迁移
-
-- 批量运行 `cr edit format`，将 compact snapshot 中旧的 `:ns $ %{} :CodeEntry ... (:schema nil) :examples []` 收敛为 `:NsEntry`
-- 运行 `cr-sync` 重写 detailed snapshot：
-  - `demos/calcit.cirru`
-  - `calcit/editor/calcit.cirru`
-- `src/cirru/calcit-core.cirru` 也已更新为 `NsEntry`
-
-## 兼容策略
-
-1. **读取兼容**：旧 snapshot/detailed snapshot 中 `ns` 仍然可以是 `CodeEntry` record
-2. **内存收敛**：加载后统一存成 `NsEntry`
-3. **保存统一**：以后重新保存或 format 都写回 `NsEntry`
-
-## 验证
-
-- `cargo fmt` ✅
-- `cargo clippy -- -D warnings` ✅
-- `cargo test` ✅
-- `yarn check-all` ✅
-
-## 备注
-
-- `demos/compact.tmp.cirru` 不是合法 snapshot，`cr edit format` 会报 EDN 解析错误，因此未纳入统一格式化
-- `demos/deps.cirru` 不是当前 snapshot loader 支持的结构，因此同样未走 `edit format`

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`