@calcit/procs 0.12.49 → 0.12.50

package/RFCs/07-19-doc-knowledge-index-rfc.md

@@ -0,0 +1,195 @@
+# RFC: 文档知识节点与增量关系索引
+
+状态：Draft  
+日期：2026-07-19  
+关联：`docs/docs-indexing.md`、`07-06-semantic-tree-navigation-rfc.md`
+
+## 1. 概要
+
+在保持 Markdown 可读、可 Git 管理的前提下，为 `cr docs` 增加一层结构化的文档知识索引：
+
+```text
+Markdown / Calcit snapshot
+        ↓
+文档节点与关系解析
+        ↓
+~/.config/calcit/docs-cache/
+        ↓
+搜索、跳转、LLM context、缺失检查
+```
+
+Markdown 和 Calcit 源码仍然是事实来源；缓存只是可以删除并重新生成的派生数据。
+
+## 2. 目标
+
+1. 文档可以表达稳定的知识节点，而不要求一次性拆分所有 Markdown。
+2. 通过 `id`、`parent`、`related`、`requires`、`leads_to` 组织树与图关系。
+3. 通过 `namespace/definition` 将文档节点关联到真实 Calcit 定义。
+4. 使用用户级 JSON 文本缓存，不引入 SQLite 或其他二进制数据库。
+5. 文件内容变化时增量失效；解析器或 schema 变化时全量失效。
+6. 能发现孤立节点、断链、未文档化定义和缺少必要章节。
+
+## 3. 非目标
+
+- 当前不引入 RDF、SPARQL、Neo4j 或 SurrealDB。
+- 当前不强制把每个章节拆成独立文件。
+- 当前不把缓存当作用户需要手工维护的知识源。
+- 当前不改变既有 `cr docs search/read` 的默认输出语义。
+
+## 4. 文档元数据
+
+现有字段继续保留：`title`、`summary`、`scope`、`kind`、`category`、`aliases`、`entry_for`。
+
+新增字段采用稳定 ID 和关系字段：
+
+```yaml
+id: api/list/nth
+code_refs:
+  - calcit.core/nth
+parent: structure/list
+related:
+  - api/list/get
+requires:
+  - concept/indexing
+leads_to:
+  - example/list-access
+```
+
+实现阶段允许使用 `x-calcit` / `extensions` 命名空间保存项目专属字段，避免污染通用 frontmatter。
+
+`id` 是语义身份；`namespace/definition` 只是代码引用，不能互相替代。
+
+## 5. 缓存模型
+
+默认位置：
+
+```text
+~/.config/calcit/docs-cache/v1/<project-id>/
+```
+
+项目身份至少包含项目根目录，避免不同项目的相对路径发生冲突。缓存还记录解析器/schema 版本和内置 Calcit core snapshot 的定义指纹；任一输入变化都会触发重建。
+
+缓存由两部分组成：
+
+```json
+{
+  "nodes": [],
+  "edges": []
+}
+```
+
+每个文件还需要记录：
+
+```json
+{
+  "path": "docs/structures/list.md",
+  "content_hash": "...",
+  "parser_version": 1,
+  "schema_version": 1,
+  "node_ids": ["structure/list"]
+}
+```
+
+内容 hash 不变时可以复用文件级解析结果；parser/schema 版本变化时必须重新解析。
+
+## 6. 关系模型
+
+树关系：
+
+- `parent`
+- `contains`
+- `leads_to`
+
+语义关系：
+
+- `related`
+- `requires`
+- `documents`
+- `implements`
+- `example_of`
+
+节点采用树形入口，关系采用独立边表，避免把循环关系硬塞进嵌套结构。
+
+## 7. 分阶段计划
+
+### Phase A：元数据兼容与增量缓存基础
+
+- 扩展 frontmatter 解析器，保留未知扩展字段的兼容空间；
+- 定义节点、边、文件缓存的 JSON schema；
+- 增加内容 hash、parser version、schema version；
+- 保持现有搜索和读取命令兼容；
+- 添加解析和失效测试。
+
+### Phase B：导航查询
+
+已完成第一版面向知识节点的查询：
+
+```bash
+cr docs graph build
+cr docs graph check
+cr docs graph children <node>
+cr docs graph related <node>
+cr docs graph path <from> <to>
+```
+
+查询当前从 Markdown 构建 JSON cache，并通过双向 BFS 查找关系路径：
+
+```bash
+cr docs graph path core/features/list core/run/edit-tree
+# core/features/list -> core/run/query -> core/run/edit-tree
+```
+
+当前已支持通过 `code_refs` 反查关联文档节点；后续再增加源码定义、示例和正文聚合：
+
+```bash
+cr docs graph explain <definition>
+```
+
+### Phase C：完整性检查
+
+```bash
+cr docs graph check
+cr docs graph orphans
+cr docs graph missing
+```
+
+检查断链、孤立节点、无正文定义、缺少示例和缺少必要章节。
+
+当前已实现：
+
+- `cr docs graph check`：检查关系边是否指向已知文档节点；
+- `cr docs graph missing [--ns <prefix>] [--limit <n>]`：按 namespace 分批检查带有 snapshot 文档说明、但没有 `code_refs` 的定义；
+- `cr docs graph orphans`：检查没有任何关系的文档节点。
+
+## 8. 验证标准
+
+- 删除缓存后，查询结果与重新构建结果一致；
+- 只修改一个 Markdown 文件时，不重新解析其他未变化文件；
+- 修改 parser/schema 版本时会全量失效；
+- 不带新增元数据的旧 Markdown 行为保持不变；
+- 缓存只包含 JSON/文本，不提交到 Git；
+- `cargo fmt`、`cargo clippy -- -D warnings`、`cargo test` 通过。
+
+### 当前验证矩阵
+
+Phase A 当前已验证：
+
+| 案例 | 结果 |
+| --- | --- |
+| 没有 frontmatter 的旧文档 | 保持空知识元数据，不影响旧搜索 |
+| 只有 `id` / `parent` | 正确解析树入口 |
+| 单值和多值关系混用 | 保持声明顺序并正确合并 |
+| `related` / `requires` / `leads_to` 交叉关系 | 可表达树外关系 |
+| 旧的 `title` / `aliases` / `entry_for` | 不会误解析为知识关系 |
+| 未闭合 frontmatter | 丢弃知识元数据，避免部分解析污染索引 |
+| 文件内容变化 | 内容 hash 失效 |
+| parser/schema 版本变化 | 缓存失效 |
+| `code_refs` 反查 definition | 返回关联文档节点 |
+| 不同项目根目录 | 缓存路径隔离 |
+| nodes/edges/files JSON 往返 | 保持结构和关系信息 |
+
+当前仍未接入的能力：
+
+- 从 Calcit snapshot 自动生成 `code_refs`（当前已加载内置 core snapshot，并校验引用是否可解析；应用/模块 snapshot 仍未接入）；
+- 自动根据 definition 的 `:examples` 检查文档示例覆盖；
+- 从 graph 节点聚合正文、schema、examples 的 LLM context。

package/RFCs/07-19-type-introspection-consistency-rfc.md

@@ -0,0 +1,73 @@
+# RFC: 类型自省(Type Introspection)一致性改进
+
+状态：Implemented（1-3 项已落地，第 4 项按计划延后）
+日期：2026-07-19
+
+---
+
+## 1. 概要
+
+调研 Calcit 当前"查询一个类型能怎么交互"的能力——有哪些字段、有哪些方法(无论是内建还是通过 trait/impl 附加的)——发现相关能力**分散在多个不对齐的 API 里**，且存在几处"数据已经在运行时结构里，但没有暴露给 Calcit 代码"的具体 gap。本 RFC 记录调研结论，并给出可落地的修复项清单。
+
+## 2. 调研结论
+
+### 2.1 方法(methods)查询——统一性最好的部分
+
+`&methods-of` / `&inspect-methods`([meta.rs](../src/builtins/meta.rs))把"内建方法"(list/map/string/number/set/fn 各自的 `&core-*-impls`)和"用户 `defimpl`/`impl-traits`"统一表示成 `CalcitImpl`，按优先级顺序去重合并，`&methods-of` 对内建/自定义一视同仁。
+
+局限：`collect_impl_records_for_value` 只接受**实例值**(`Tuple`/`Record`/`List`/`Map`/`Number`/`Str`/`Set`/`Fn`/`Proc`)，不接受裸的 `Calcit::Struct`/`Calcit::Enum`/`Calcit::Trait`(类型定义本身)。也就是说 `&methods-of Person`(还没造实例)会直接报错，必须先构造一个实例才能查询"这个类型将来会有哪些方法"。
+
+`NativeMethodsOf` 的类型签名是 `arg_types: vec![dynamic_tag()]`（[proc_name.rs](../src/calcit/proc_name.rs)），说明这一限制纯粹是**运行时实现**的限制，不是类型检查器强加的——修复它不需要碰类型系统。
+
+### 2.2 字段(fields)查询——能用，但类型签名与实现脱节
+
+`to-pairs`/`keys`/`&record:to-map` 在运行时(`to_pairs` in [maps.rs](../src/builtins/maps.rs))原生支持 `Calcit::Record`，能拿到字段名（tag）。
+
+但 `ToPairs` 的类型签名声明 `arg_types: vec![some_tag("map")]`，而 `matches_with_bindings`([type_annotation.rs](../src/calcit/type_annotation.rs))里 `(TypeRef("map"), Record(base))` 这一分支是拿 `"map"` 去匹配 `base.name`（即结构体自己的名字，比如 `"Person"`），显然不相等 → **对 record 调用 `to-pairs`/`keys` 会在类型检查阶段被判定为类型不匹配并产生告警**，即便运行时完全正确。这是文档/类型签名与实际能力脱节的具体例子。
+
+没有实例、只有裸类型定义时（刚 `defstruct Person ...` 还没构造实例），**没有**可编程 API 能拿到字段名列表当数据用；唯一能看到字段的方式是 `println`/`str` 对 struct 值做格式化输出人肉读。
+
+### 2.3 `Display`（`println`/`str`）在三种类型定义值之间不对称
+
+`impl fmt::Display for Calcit`（[calcit.rs](../src/calcit.rs)）：
+
+| 类型定义值 | 输出示例 | 包含信息 |
+| --- | --- | --- |
+| `Struct` | `(%struct :Person (:name string) (:age number))` | 字段名 + 类型 |
+| `Trait` | `(trait Name :m1 :m2)` | 仅方法名，**没有**方法签名类型 |
+| `Enum` | `(%enum :Name)` | **仅名字**，连 variant 列表都没有 |
+
+`CalcitEnum` 内部其实完整保存着 `variants()`（tag + payload_types，见 [sum_type.rs](../src/calcit/sum_type.rs)），数据都在，只是没接到 `Display` 里——这是一处"能力已具备却未暴露"的明显 gap，且没有任何测试覆盖这个输出格式（`grep "%struct"`/`"%enum"` 在 `calcit/*.cirru` 测试里零命中）。
+
+### 2.4 结论
+
+- 没有一个统一的"describe 类型"入口能同时列出 fields + methods（不管来源）；需要组合调用不同风格的 API。
+- 对"类型定义本身"（还未实例化）的支持最弱：`&methods-of` 不接受、字段列表没有编程接口、`Enum`/`Trait` 的打印格式也比 `Struct` 缺信息。
+
+## 3. 修复计划(按优先级/风险排序)
+
+1. ✅ **`Enum` 的 `Display` 补上 variants**（最小、最安全，纯展示层修复，无 API 变化）。
+   - 实现：[src/calcit.rs](../src/calcit.rs) `impl fmt::Display for Calcit` 的 `Enum` 分支，现在遍历 `enum_def.variants()` 输出 `(:tag type1 type2 ...)`。
+   - 测试：`enum_display_includes_variants`（同文件 `#[cfg(test)] mod tests`）。
+2. ✅ **`&methods-of` 接受裸 `Struct`/`Enum`/`Trait` 值**（直接读它们自带的 `impls` 字段），不再强制要求实例。
+   - 实现：[src/builtins/meta.rs](../src/builtins/meta.rs) `collect_impl_records_for_value` 新增 `Struct`/`Enum` 分支；`iter_impls_in_precedence_order` 把 `Struct`/`Enum` 纳入与 `Tuple`/`Record` 相同的“后定义优先”倒序规则；`Trait` 单独处理（直接读 `trait_def.methods`，因为 trait 本身没有 `impls` 字段，是直接声明方法名）。`methods_of`/`inspect_methods` 都做了对应分支。
+   - JS 同步：[ts-src/calcit.procs.mts](../ts-src/calcit.procs.mts) 的 `lookup_impls`/`_$n_methods_of`/`_$n_inspect_methods` 同步补齐 `CalcitStruct`/`CalcitEnum`/`CalcitTrait` 分支。
+   - 测试：[calcit/test-traits.cirru](../calcit/test-traits.cirru) 的 `test-method-introspection` 新增对 `impl-traits Person0 MyFooImpl`（裸 struct）、`DemoBar`（裸 enum）、`MyFoo`（裸 trait）调用 `&methods-of` 的断言，`yarn check-all`（rs/js/ir/wasm 四目标）全部通过。
+3. ✅ **修正 `to-pairs`/`keys` 的类型签名**，让 record 也能匹配，消除虚假类型告警。
+   - 实现：[src/calcit/type_annotation.rs](../src/calcit/type_annotation.rs) `matches_with_bindings` 里 `(TypeRef, Record)` 分支新增：当 `TypeRef` 名字就是泛化的 `"map"` 时，结构性地匹配任意 record（不要求 record 名字等于 `"map"`）。
+   - 测试：新增单元测试 `generic_map_type_ref_accepts_records_structurally`，直接验证 `TypeRef("map")` 与 `Record(Person)` 现在双向匹配，同时确认无关的 `TypeRef` 名字仍然不会误匹配。
+   - 备注：实测 `cr --check-only` 在当前仓库测试集里并未因这个 gap 产生可观察的告警（`test-record.cirru` 里 `keys p2` 这行本来就没有触发过告警，猜测是这条路径上的静态类型推断没有把 `p2` 识别为具体的 `Record` 类型，所以没有触发 `check_proc_arg_types` 这条检查分支）。但 `matches_with_bindings` 的错误比较逻辑本身是真实存在的 bug，属于防御性修复：一旦未来静态推断能力增强（例如给变量加显式类型标注后传入 `to-pairs`/`keys`），就不会再误报。
+4. ⏸️ **（可选，视时间，本轮未实现）** 新增 `&struct:fields`/`&enum:variants` 之类的编程接口，让“裸类型定义”的字段/variant 列表也能被程序消费，而不仅仅是打印文本。
+   - 未实现原因：新增一个 proc 需要贯穿 `proc_name.rs`(注册+类型签名)、`builtins.rs`(分发)、`builtins/records.rs`或`meta.rs`(实现)、以及 JS/IR/WASM 三个 codegen 目标的同步实现，工作量与收益相比前三项更低（前三项已经解决了运行时能力不对齐的核心问题；字段/variant 名字目前仍可通过 `Display`/`println` 人肉获取，只是没有编程接口）。留作后续独立迭代。
+
+## 4. 兼容性 / 风险
+
+- 第 1、2、3 项都已实现并通过 `cargo test`、`cargo run --bin cr -- calcit/test.cirru`、`yarn check-all`、`cargo clippy -- -D warnings`、`cargo fmt` 验证，纯粹的能力扩展/告警范围放宽，不改变现有行为，向后兼容。
+- 第 4 项延后，不影响现有行为。
+
+## 5. 验证方式（已执行）
+
+- `cargo test`：新增/更新的 Rust 单元测试全部通过，覆盖 `Display for Enum`、`&methods-of` 对裸类型定义的调用、`to-pairs`/`keys` 的类型匹配放宽。
+- `cargo run --bin cr -- calcit/test.cirru`：Cirru 集成测试套件全部通过，包括新增的裸类型 `&methods-of` 断言。
+- `yarn check-all`：JS/IR/WASM 三个目标同步验证通过（`&methods-of` 的 JS 实现已同步补齐）。
+- `cargo clippy -- -D warnings` / `cargo fmt`：均无告警。

package/RFCs/README.md

@@ -30,6 +30,8 @@
 | `06-15-effects-graph-rfc.md`                        | Draft         | `cr analyze effects-graph`：State/Transform/Effect 语义分解图与类型驱动 effect 标注路线。 |
 | `06-29-cr-exec-cli-builtins-rfc.md`                 | **Active**    | `cr exec` + `calcit.cli/*` 内建函数：绕过 Shell 转义的 Cirru 函数调用方案。               |
 | `07-06-semantic-tree-navigation-rfc.md`             | Draft         | 语义化树形导航与编辑：路径标注、多候选交互、锚点搜索替换、结构化查询语言。                |
+| `07-19-doc-knowledge-index-rfc.md`                  | Draft         | Markdown/Calcit snapshot 的知识节点、关系索引与用户级增量缓存方案。                       |
+| `07-19-type-introspection-consistency-rfc.md`       | Implemented   | 类型自省一致性改进：`&methods-of` 支持裸类型定义、`Enum` Display 补 variants、`to-pairs`/`keys` 类型签名修正（第 4 项可选新增 proc 延后）。 |
 
 ## 已执行的清理
 

package/build.rs

@@ -305,10 +305,8 @@ fn parse_code_entry(edn: Edn, owner: &str) -> Result<CodeEntry, String> {
       "examples" => examples = from_edn(value.clone()).map_err(|e| format!("{owner}: invalid `:examples`: {e}"))?,
       "tags" => tags = parse_tags_from_edn(value, owner)?,
       "code" => code = Some(from_edn(value.clone()).map_err(|e| format!("{owner}: invalid `:code`: {e}"))?),
-      "schema" => {
-        if !matches!(value, Edn::Nil) {
-          schema = Some(parse_schema_from_edn(value, owner).map_err(|e| format!("{owner}: invalid `:schema`: {e}"))?);
-        }
+      "schema" if !matches!(value, Edn::Nil) => {
+        schema = Some(parse_schema_from_edn(value, owner).map_err(|e| format!("{owner}: invalid `:schema`: {e}"))?);
       }
       _ => {}
     }

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

@@ -0,0 +1,40 @@
+## 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-07-07-0000-semantic-tree-navigation.md

@@ -7,38 +7,43 @@
 ## 实现功能
 
 ### L1: `--path-annotations`
+
 - `cr tree show` 新增 `--path-annotations` flag
 - 开启后递归为所有嵌套 `Cirru::List` 末尾追加 `; "previous node path: X.Y.Z"` 注释节点
 - AST 层面操作：`children.push(Cirru::List([Cirru::Leaf(";"), Cirru::Leaf(path_string)]))`
 - 子节点 > 8 时底部 tip 提示可开启
 
 ### L2: `--pick` 多候选选择
+
 - `search-replace` 多匹配时展示带路径、上下文的候选列表
 - `--pick <N>` 直接选择第 N 个候选执行替换
 
 ### L4: 语义路径表达式
+
 - `cr query path <ns> --selector 'path heading ... nth ...'`
 - 三个选择器：裸叶子（精确匹配）、`heading`（前缀匹配）、`nth`（位置导航）
 - `resolve_path_expression` 函数解析并返回数字路径
 
 ### L4: `--selector` 限定搜索范围
+
 - `search-replace --selector 'path ...'` 在语义路径定位的子树内搜索替换
 - 与 `cr query path` 共用同一套选择器语法
 
 ### Phase 4: `cr query anchors`
+
 - 遍历 AST 中 `noted @anchor:<name>` 调用，输出锚点名称和路径
 
 ## 修改文件
 
-| 文件 | 变更 |
-|------|------|
-| `src/cli_args.rs` | 新增 `path_annotations`, `pick`, `selector` 字段；新增 `QueryPathCommand`, `QueryAnchorsCommand` |
-| `src/bin/cli_handlers/tree.rs` | `annotate_paths` 函数；`handle_show` 路径标注 + tip；`handle_search_replace` 多候选 + selector |
-| `src/bin/cli_handlers/query.rs` | `resolve_path_expression`(pub), `starts_with_pattern`, `handle_query_path`, `handle_query_anchors`, `find_anchors` |
-| `src/bin/cli_handlers/command_echo.rs` | Path/Anchors 子命令 echo 支持 |
-| `docs/CalcitAgent.md` | 精简引用新功能 |
-| `docs/run/agent-advanced.md` | 详细示例文档 |
-| `RFCs/07-06-semantic-tree-navigation-rfc.md` | 新增 RFC |
+| 文件                                         | 变更                                                                                                               |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `src/cli_args.rs`                            | 新增 `path_annotations`, `pick`, `selector` 字段；新增 `QueryPathCommand`, `QueryAnchorsCommand`                   |
+| `src/bin/cli_handlers/tree.rs`               | `annotate_paths` 函数；`handle_show` 路径标注 + tip；`handle_search_replace` 多候选 + selector                     |
+| `src/bin/cli_handlers/query.rs`              | `resolve_path_expression`(pub), `starts_with_pattern`, `handle_query_path`, `handle_query_anchors`, `find_anchors` |
+| `src/bin/cli_handlers/command_echo.rs`       | Path/Anchors 子命令 echo 支持                                                                                      |
+| `docs/CalcitAgent.md`                        | 精简引用新功能                                                                                                     |
+| `docs/run/agent-advanced.md`                 | 详细示例文档                                                                                                       |
+| `RFCs/07-06-semantic-tree-navigation-rfc.md` | 新增 RFC                                                                                                           |
 
 ## 设计决策
 

package/editing-history/2026-07-08-1650-features-and-js-object-type.md

@@ -3,6 +3,7 @@
 ## Changes
 
 ### Feature: `:features` and `:js-object` type system
+
 - Added `features: Arc<HashSet<EdnTag>>` to `CalcitFnTypeAnnotation` for marking function capabilities
 - Added `CalcitTypeAnnotation::JsObject` variant for opaque JS FFI data
 - EDN round-trip for both (`features_to_edn` + `parse_fn_features_from_form`)
@@ -14,6 +15,7 @@
 - All direct FFI callers marked with `:features $ #{} :js-ffi`
 
 ### Refactor: CLI simplification
+
 - Removed `--json` option and `--json-input` switch from all edit/tree subcommands
 - Auto-detect JSON (`[` prefix) vs Cirru EDN (`quote` prefix) in `parse_input_to_cirru`
 - Simplified `read_code_input` to `(file, code)` params; stdin fallback

package/editing-history/2026-07-09-1700-concise-method-representation.md

@@ -0,0 +1,8 @@
+# Edit History - Concise Method Representation and Introspection Refactoring
+
+- **Objective**: Improve the representation of methods inside the VM to return first-class `Calcit::Method` values rather than strings from `&methods-of`, and provide a concise, user-facing rendering suitable for REPL and dynamic inspection rather than verbose list expressions, all while keeping internal preprocessing unaffected.
+- **Actions**:
+  - Refactored `methods_of` in `src/builtins/meta.rs` to return native `Calcit::Method` values directly with leading dots stripped.
+  - Implemented custom `turn_string` in `src/calcit.rs` for `Calcit::Method` to format method values concisely (e.g., `.add`, `.-field`, `.!native`) for `str` conversions, prints, and dynamic assertions.
+  - Updated `format_to_lisp` in `src/calcit.rs` to keep `format_to_lisp` compatible with internal macros (like `deftrait` which dynamically slices `format-to-lisp` output starting from the 9th character).
+  - Cleaned up assertions inside `calcit/test-traits.cirru`'s `test-method-introspection` to map `&methods-of` outputs to string using `str` rather than raw assertion of methods list, ensuring absolute compatibility and safety.

package/editing-history/2026-07-19-1919-type-introspection-consistency.md

@@ -0,0 +1,24 @@
+# Edit History - Type Introspection Consistency Fixes
+
+- **Objective**: Close gaps found while researching "how to discover a type's fields/methods in Calcit" (methods via traits/impls, fields via records, Display formatting). Documented findings and a prioritized fix plan in `RFCs/07-19-type-introspection-consistency-rfc.md`, then implemented items 1-3 (item 4 deferred as optional/out of scope for this pass).
+
+- **Fix 1 — `Enum` `Display` now includes variants** (`src/calcit.rs`):
+  - Previously `Calcit::Enum` printed only `(%enum :Name)`, discarding the already-tracked `variants()` (tag + payload types). Now prints `(%enum :Name (:variant1 type ...) (:variant2 ...) ...)`, matching the richness of `Struct`'s Display.
+  - Test: `enum_display_includes_variants` in `src/calcit.rs`'s test module.
+
+- **Fix 2 — `&methods-of`/`&inspect-methods` accept bare `Struct`/`Enum`/`Trait` values** (not just instances):
+  - `src/builtins/meta.rs`: `collect_impl_records_for_value` gained `Calcit::Struct`/`Calcit::Enum` arms (read their own `impls` field directly). `iter_impls_in_precedence_order` now treats `Struct`/`Enum` the same as `Tuple`/`Record` (last-attached impl wins, i.e. reversed iteration) since `&struct:impl-traits`/`&enum:impl-traits` also `.extend()` impls onto the end.
+  - `Calcit::Trait` handled as a special case (new helper `trait_dot_method_names`) since traits declare methods directly, not via an `impls` list — no `impls` field exists on `CalcitTrait`.
+  - JS target parity: `ts-src/calcit.procs.mts`'s `lookup_impls` gained `CalcitStruct`/`CalcitEnum` branches; the `reverse`-order flag (previously only `CalcitRecord || CalcitTuple`) now also includes `CalcitStruct || CalcitEnum`; `_$n_methods_of`/`_$n_inspect_methods` special-case `CalcitTrait` the same way as the Rust side.
+  - Test: `calcit/test-traits.cirru`'s `test-method-introspection` — new `let` block calling `&methods-of` on `(impl-traits Person0 MyFooImpl)` (bare struct), `DemoBar` (bare enum), `MyFoo` (bare trait), asserting the expected method tags show up. Edited via `cr tree insert-after` (module entry must be the module's own file, e.g. `cr calcit/test-traits.cirru ...`, NOT the aggregated `calcit/test.cirru` — `cr tree`/`cr edit` couldn't resolve the namespace when invoked through the aggregator, while `cr query` could).
+
+- **Fix 3 — `to-pairs`/`keys` type signature no longer false-warns on records**:
+  - `src/calcit/type_annotation.rs`: `matches_with_bindings`'s `(TypeRef, Record)` arm previously only matched if the `TypeRef` name equaled the record's own struct name (e.g. `"map"` vs `"Person"` → false). Added: when the `TypeRef` name is the generic `"map"` placeholder, match any record structurally (records are field-name → value, i.e. map-like), in addition to the existing exact-name match.
+  - Test: `generic_map_type_ref_accepts_records_structurally` in `src/calcit/type_annotation.rs`'s test module — verifies `TypeRef("map")` matches `Record(Person)` both directions, and confirms unrelated `TypeRef` names still don't match structurally (no over-broadening).
+  - Note: empirically, `cr --check-only` on `test-record.cirru` didn't show a warning for `keys p2` even before this fix (likely because that call site's static type inference doesn't currently narrow `p2` to `Record`), so this is a defensive/forward-looking fix for when static inference improves or explicit type annotations are used, not a fix for an observed regression today.
+
+- **Deferred (RFC item 4, optional)**: `&struct:fields`/`&enum:variants` new introspection procs — would require registering a new `CalcitProc` end-to-end (proc_name.rs signature + string mapping, builtins.rs dispatch, records.rs/meta.rs impl, JS/IR/WASM codegen parity). Judged lower priority/cost-to-benefit than items 1-3 which fixed real capability gaps; left as a follow-up.
+
+- **Tooling note**: `cr tree`/`cr edit` subcommands need the entry file to be the *specific module's own `.cirru` file* (e.g. `calcit/test-traits.cirru`) to resolve `<ns>/<def>` targets — passing the aggregator entry (`calcit/test.cirru`, which just lists the module in `:modules`) causes `Error: "Namespace '...' not found"` for `tree`/`edit` even though `cr query defs/def` works fine through the aggregator. `--file` snippet content must be `quote`-prefixed (e.g. `quote (let (...) ...)`) even though the repo's `Agents.md` `--stdin` removal note doesn't mention this requirement explicitly.
+
+- **Validation**: `cargo fmt`, `cargo clippy -- -D warnings`, `cargo test` (239 lib tests incl. 2 new), `cargo run --bin cr -- calcit/test.cirru`, `yarn check-all` (compile + try-rs + try-js + try-ir + try-wasm) — all clean/passing.

package/editing-history/2026-07-19-1930-schema-tag-roundtrip-fix.md

@@ -0,0 +1,64 @@
+# Schema kind tag round-trip regression fix (2026-07-19 19:30)
+
+## Symptom
+
+Running `cr tree insert-after`/`cr edit` on [calcit/test-traits.cirru](../calcit/test-traits.cirru)
+(to add new `test-method-introspection` assertions) silently rewrote the `:schema`
+field of *every other, unrelated* def in the same file from its specific kind tag
+(`:enum`, `:trait`, `:impl`, `:struct`) down to `:schema :dynamic`. This affected
+~15 defs (`Demo0`, `DemoBar`, `MyBar`, `MyBarImpl`, `MyFoo`, `MyFooImpl`, `Person0`,
+etc.) that were never touched by the edit itself — any save of the file degraded
+their schema fidelity as a side effect.
+
+## Root cause
+
+`:struct`/`:enum`/`:trait`/`:impl`/`:record` shorthand schema tags load into
+`CalcitTypeAnnotation::Custom(Arc<Calcit>)` (see `CalcitTypeAnnotation::from_tag_name`
+in [src/calcit/type_annotation.rs](../src/calcit/type_annotation.rs)), wrapping the
+kind as a bare `Calcit::Tag`. On save, `schema_annotation_to_edn` (in
+[src/snapshot.rs](../src/snapshot.rs)) converted the in-memory schema back to EDN via
+`CalcitTypeAnnotation::builtin_tag_name()`, which only handles primitive scalar
+types (`bool`, `number`, `string`, ...) and has no arm for `Custom`, `Record`,
+`Struct`, `Enum`, or `Trait` — those all fell through the `_ => None` catch-all,
+so `schema_annotation_to_edn` silently defaulted to `Edn::tag("dynamic")`.
+
+Since `code_entry_edn_pairs` recomputes every entry's schema EDN from its in-memory
+`CalcitTypeAnnotation` on *every* file save (not just for touched defs), any
+`cr edit`/`cr tree` write to a file containing these shorthand-tagged schemas
+degrades them all to `:dynamic`, regardless of which def was actually edited.
+
+Note `builtin_tag_name()` is also used by `to_brief_string()` and other call
+sites that intentionally want more specific output (e.g. `struct Person` instead
+of a bare `:struct`) for those variants — so widening `builtin_tag_name()` itself
+to cover them would have regressed those call sites. The fix instead lives
+directly in `schema_annotation_to_edn`, which is the one place that needs the
+short kind-tag representation for the snapshot file format.
+
+## Fix
+
+Added explicit match arms to `schema_annotation_to_edn` in [src/snapshot.rs](../src/snapshot.rs):
+- `Custom(value)`: coerce the wrapped `Calcit::Tag` back into its `Edn::Tag` (falls
+  back to `:dynamic` only if the wrapped value isn't a bare tag, which shouldn't
+  happen via `from_tag_name`).
+- `Record(_)` → `:record`, `Struct(..)` → `:struct`, `Enum(..)` → `:enum`,
+  `Trait(_)` → `:trait`.
+
+This preserves the user's original expressed intent (e.g. `:schema :impl`) instead
+of silently downgrading it to `:dynamic`, which would otherwise turn off
+schema-based type-checking coverage for those defs.
+
+Recovered the previously-corrupted `calcit/test-traits.cirru` by reverting to
+`git checkout` and reapplying the new `test-method-introspection` assertions with
+the fixed binary — confirmed via `git diff` that this time only the intended
+7 new lines changed, with zero incidental `:schema` churn.
+
+## Regression test
+
+`test_custom_kind_schema_tags_round_trip_instead_of_degrading_to_dynamic` in
+[src/snapshot.rs](../src/snapshot.rs) asserts `schema_annotation_to_edn(CalcitTypeAnnotation::from_tag_name(kind))`
+round-trips to `Edn::tag(kind)` for `struct`/`enum`/`trait`/`impl`/`record`.
+
+## Validation
+
+`cargo fmt`, `cargo clippy --all-targets -- -D warnings`, `cargo test` (all pass),
+`yarn check-all` (exit 0).

package/editing-history/20260719-2236-doc-knowledge-graph.md

@@ -0,0 +1,27 @@
+# 2026-07-19 22:36 文档知识图谱与增量缓存
+
+## 修改概要
+
+- 为 `cr docs` 增加文档知识图构建、检查、关系遍历、路径查询、定义反查、缺失定义和孤立节点命令。
+- 使用 Markdown frontmatter 的 `id`、`parent`、`related`、`requires`、`leads_to`、`code_refs` 表达可 Git 管理的知识关系。
+- 在 `~/.config/calcit/docs-cache/` 生成 JSON 文本缓存，按文件内容、解析器/schema 版本和内置 Calcit snapshot 指纹失效。
+- 为文档索引 RFC、`CalcitAgent.md`、索引规范和验证案例补充使用说明。
+- 为核心数据结构文档补充稳定节点 ID 与 Calcit 定义引用，验证从概念到 API 和编辑工作流的跳转。
+
+## 验证
+
+- `cargo fmt --all`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo test -q`
+- `yarn compile`
+- `cr docs graph build`
+- `cr docs graph check`
+- `cr docs graph path core/features/list core/run/edit-tree`
+- `cr docs graph explain calcit.core/nth`
+- `cr docs graph missing`
+- `cr docs graph orphans`
+
+## 后续方向
+
+- 将 `missing` 从总量报告扩展为按公共 API、语法符号和内部定义分类。
+- 接入模块或应用级 Calcit snapshot，并增加示例覆盖检查与 LLM context 聚合。

package/editing-history/20260719-2245-doc-graph-missing-filter.md

@@ -0,0 +1,17 @@
+# 2026-07-19 22:45 graph missing 分批筛选
+
+## 修改概要
+
+- 为 `cr docs graph missing` 增加 `--ns` namespace 前缀过滤。
+- 增加 `--limit` 输出数量限制，便于按批次补充公共 API 的 `code_refs`。
+- 在 `CalcitAgent.md` 和知识图谱 RFC 中补充该操作说明。
+- 增加 namespace 过滤、数量限制和内部命名排除的单元测试。
+
+## 验证
+
+- `cargo fmt --all`
+- `cargo test -q`
+- `cargo clippy --all-targets -- -D warnings`
+- `yarn compile`
+- `cr docs graph missing --ns calcit.core --limit 5`
+- `git diff --check`

package/editing-history/20260719-2310-doc-graph-explain-full.md

@@ -0,0 +1,16 @@
+# 2026-07-19 23:10 graph explain 定义摘要
+
+## 修改概要
+
+- 为 `cr docs graph explain` 增加 `--full`，输出 Calcit 定义的 doc 和 examples 可用性。
+- 缓存定义记录保存 doc 文本，并将 cache schema 升级为 5，确保旧缓存自动重建。
+- 更新 command echo、`CalcitAgent.md` 和 graph 验证案例。
+
+## 验证
+
+- `cargo fmt --all`
+- `cargo test -q`
+- `cargo clippy --all-targets -- -D warnings`
+- `yarn compile`
+- `cr docs graph explain calcit.core/nth --full`
+- `git diff --check`

package/lib/calcit-data.mjs

@@ -210,6 +210,14 @@ export let hashFunction = (x) => {
         return h;
     }
     if (typeof x === "function") {
+        // method values are closures created on the fly (see invoke_method_closure);
+        // hash by method name so equal methods share the same hash, matching isEqual
+        const methodName = x.__calcitMethodName;
+        if (methodName != null) {
+            let h = mergeValueHash(defaultHash_fn, methodName);
+            x[calcit_dirty_hash_key] = h;
+            return h;
+        }
         fnHashCounter = fnHashCounter + 1;
         let h = mergeValueHash(defaultHash_fn, fnHashCounter);
         x[calcit_dirty_hash_key] = h;
@@ -383,6 +391,10 @@ export let toString = (x, escaped, disableJsDataWarning = false) => {
         return x.toString();
     }
     if (typeof x === "function") {
+        const methodName = x.__calcitMethodName;
+        if (methodName != null) {
+            return "." + methodName;
+        }
         return `(&fn ...)`;
     }
     if (x instanceof CalcitSymbol) {
@@ -541,7 +553,14 @@ export let _$n__$e_ = (x, y) => {
         return false;
     }
     if (tx === "function") {
-        // comparing functions by reference
+        // method values are closures created on the fly (see invoke_method_closure),
+        // so two methods with the same name must compare equal by name, not by reference
+        const mx = x.__calcitMethodName;
+        const my = y.__calcitMethodName;
+        if (mx != null || my != null) {
+            return mx === my;
+        }
+        // comparing plain functions by reference
         return x === y;
     }
     if (x instanceof CalcitTag) {

package/lib/calcit.procs.mjs

@@ -1834,6 +1834,17 @@ function lookup_impls(obj) {
         tag = "&core-set-methods";
         impls = normalize_builtin_impls(calcit_builtin_impls.set);
     }
+    else if (obj instanceof CalcitStruct) {
+        // Bare type definitions (not yet instantiated) carry their own attached
+        // impls, so introspection tools like `&methods-of` can answer "what
+        // methods will instances of this type have" without a concrete instance.
+        tag = obj.name.toString();
+        impls = obj.impls;
+    }
+    else if (obj instanceof CalcitEnum) {
+        tag = obj.name();
+        impls = obj.impls;
+    }
     else if (typeof obj === "number") {
         tag = "&core-number-methods";
         impls = normalize_builtin_impls(calcit_builtin_impls.number);
@@ -1862,7 +1873,7 @@ export function invoke_method(p, obj, ...args) {
     let tag = pair[1];
     // builtin impl lists are ordered by priority in calcit-core.
     // user-defined values use impl-traits append, so later impls override earlier ones.
-    let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple;
+    let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple || obj instanceof CalcitStruct || obj instanceof CalcitEnum;
     let idx = reverse ? impls.length - 1 : 0;
     while (reverse ? idx >= 0 : idx < impls.length) {
         let klass = impls[idx];
@@ -1882,12 +1893,16 @@ export function invoke_method(p, obj, ...args) {
 export function _$n_methods_of(obj) {
     if (arguments.length !== 1)
         throw new Error("&methods-of expected 1 argument");
+    // Traits declare methods directly rather than through attached impls.
+    if (obj instanceof CalcitTrait) {
+        return new CalcitSliceList(obj.methods.map((m) => invoke_method_closure(m.value)));
+    }
     let pair = lookup_impls(obj);
     if (pair == null) {
         throw new Error(`&methods-of cannot resolve impls for: ${toString(obj, true)}`);
     }
     let impls = pair[0];
-    let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple;
+    let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple || obj instanceof CalcitStruct || obj instanceof CalcitEnum;
     let seen = new Set();
     let ys = [];
     let idx = reverse ? impls.length - 1 : 0;
@@ -1895,10 +1910,11 @@ export function _$n_methods_of(obj) {
         let impl = impls[idx];
         if (impl != null) {
             for (let k = 0; k < impl.fields.length; k++) {
-                let name = "." + impl.fields[k].value;
+                let rawName = impl.fields[k].value;
+                let name = "." + rawName;
                 if (!seen.has(name)) {
                     seen.add(name);
-                    ys.push(name);
+                    ys.push(invoke_method_closure(rawName));
                 }
             }
         }
@@ -1909,12 +1925,26 @@ export function _$n_methods_of(obj) {
 export function _$n_inspect_methods(obj, note) {
     if (arguments.length !== 2)
         throw new Error("&inspect-methods expected 2 arguments");
+    if (obj instanceof CalcitTrait) {
+        console.log("\n&inspect-methods");
+        console.log(`Note: ${toString(note, true)}`);
+        console.log(`Value type: ${type_of(obj).toString()}`);
+        console.log(`Value: ${toString(obj, true)}`);
+        console.log("Method call syntax: `.method self p1 p2`");
+        console.log("  - dot is part of the method name, first arg is the receiver\n");
+        const names = obj.methods.map((m) => "." + m.value);
+        console.log(`Trait methods declared directly (no impls): ${names.length}`);
+        console.log(`\nAll methods (unique, high → low): ${names.length}`);
+        console.log("  " + names.join(" "));
+        console.log("\n");
+        return obj;
+    }
     let pair = lookup_impls(obj);
     if (pair == null) {
         throw new Error(`&inspect-methods cannot resolve impls for: ${toString(obj, true)}`);
     }
     let impls = pair[0];
-    let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple;
+    let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple || obj instanceof CalcitStruct || obj instanceof CalcitEnum;
     console.log("\n&inspect-methods");
     console.log(`Note: ${toString(note, true)}`);
     console.log(`Value type: ${type_of(obj).toString()}`);
@@ -1941,7 +1971,7 @@ export function _$n_inspect_methods(obj, note) {
     }
     let ms = _$n_methods_of(obj);
     console.log(`\nAll methods (unique, high → low): ${ms.len()}`);
-    console.log("  " + Array.from(ms.items()).join(" "));
+    console.log("  " + Array.from(ms.items()).map((m) => toString(m, false)).join(" "));
     console.log("\n");
     return obj;
 }
@@ -1963,7 +1993,7 @@ export function _$n_trait_call(traitDef, method, obj, ...args) {
         throw new Error(`&trait-call cannot resolve impls for: ${toString(obj, true)}`);
     }
     const impls = pair[0];
-    const reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple;
+    const reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple || obj instanceof CalcitStruct || obj instanceof CalcitEnum;
     let idx = reverse ? impls.length - 1 : 0;
     while (reverse ? idx >= 0 : idx < impls.length) {
         const impl = impls[idx];

package/lib/package.json

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

package/package.json

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

package/ts-src/calcit-data.mts

@@ -238,6 +238,14 @@ export let hashFunction = (x: CalcitValue): Hash => {
     return h;
   }
   if (typeof x === "function") {
+    // method values are closures created on the fly (see invoke_method_closure);
+    // hash by method name so equal methods share the same hash, matching isEqual
+    const methodName = (x as { __calcitMethodName?: string }).__calcitMethodName;
+    if (methodName != null) {
+      let h = mergeValueHash(defaultHash_fn, methodName);
+      (x as any)[calcit_dirty_hash_key] = h;
+      return h;
+    }
     fnHashCounter = fnHashCounter + 1;
     let h = mergeValueHash(defaultHash_fn, fnHashCounter);
     (x as any)[calcit_dirty_hash_key] = h;
@@ -412,6 +420,10 @@ export let toString = (x: CalcitValue, escaped: boolean, disableJsDataWarning: b
     return x.toString();
   }
   if (typeof x === "function") {
+    const methodName = (x as { __calcitMethodName?: string }).__calcitMethodName;
+    if (methodName != null) {
+      return "." + methodName;
+    }
     return `(&fn ...)`;
   }
   if (x instanceof CalcitSymbol) {
@@ -579,7 +591,14 @@ export let _$n__$e_ = (x: CalcitValue, y: CalcitValue): boolean => {
     return false;
   }
   if (tx === "function") {
-    // comparing functions by reference
+    // method values are closures created on the fly (see invoke_method_closure),
+    // so two methods with the same name must compare equal by name, not by reference
+    const mx = (x as { __calcitMethodName?: string }).__calcitMethodName;
+    const my = (y as { __calcitMethodName?: string }).__calcitMethodName;
+    if (mx != null || my != null) {
+      return mx === my;
+    }
+    // comparing plain functions by reference
     return x === y;
   }
   if (x instanceof CalcitTag) {

package/ts-src/calcit.procs.mts

@@ -1946,6 +1946,15 @@ function lookup_impls(obj: CalcitValue): [CalcitImpl[], string] {
   } else if (obj instanceof CalcitSet) {
     tag = "&core-set-methods";
     impls = normalize_builtin_impls(calcit_builtin_impls.set);
+  } else if (obj instanceof CalcitStruct) {
+    // Bare type definitions (not yet instantiated) carry their own attached
+    // impls, so introspection tools like `&methods-of` can answer "what
+    // methods will instances of this type have" without a concrete instance.
+    tag = obj.name.toString();
+    impls = obj.impls;
+  } else if (obj instanceof CalcitEnum) {
+    tag = obj.name();
+    impls = obj.impls;
   } else if (typeof obj === "number") {
     tag = "&core-number-methods";
     impls = normalize_builtin_impls(calcit_builtin_impls.number);
@@ -1971,7 +1980,7 @@ export function invoke_method(p: string, obj: CalcitValue, ...args: CalcitValue[
   let tag = pair[1];
   // builtin impl lists are ordered by priority in calcit-core.
   // user-defined values use impl-traits append, so later impls override earlier ones.
-  let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple;
+  let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple || obj instanceof CalcitStruct || obj instanceof CalcitEnum;
   let idx = reverse ? impls.length - 1 : 0;
   while (reverse ? idx >= 0 : idx < impls.length) {
     let klass = impls[idx];
@@ -1991,12 +2000,16 @@ export function invoke_method(p: string, obj: CalcitValue, ...args: CalcitValue[
 
 export function _$n_methods_of(obj: CalcitValue): CalcitSliceList {
   if (arguments.length !== 1) throw new Error("&methods-of expected 1 argument");
+  // Traits declare methods directly rather than through attached impls.
+  if (obj instanceof CalcitTrait) {
+    return new CalcitSliceList(obj.methods.map((m) => invoke_method_closure(m.value)));
+  }
   let pair = lookup_impls(obj);
   if (pair == null) {
     throw new Error(`&methods-of cannot resolve impls for: ${toString(obj, true)}`);
   }
   let impls = pair[0];
-  let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple;
+  let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple || obj instanceof CalcitStruct || obj instanceof CalcitEnum;
   let seen = new Set<string>();
   let ys: CalcitValue[] = [];
 
@@ -2005,10 +2018,11 @@ export function _$n_methods_of(obj: CalcitValue): CalcitSliceList {
     let impl = impls[idx];
     if (impl != null) {
       for (let k = 0; k < impl.fields.length; k++) {
-        let name = "." + impl.fields[k].value;
+        let rawName = impl.fields[k].value;
+        let name = "." + rawName;
         if (!seen.has(name)) {
           seen.add(name);
-          ys.push(name);
+          ys.push(invoke_method_closure(rawName));
         }
       }
     }
@@ -2019,12 +2033,26 @@ export function _$n_methods_of(obj: CalcitValue): CalcitSliceList {
 
 export function _$n_inspect_methods(obj: CalcitValue, note: CalcitValue): CalcitValue {
   if (arguments.length !== 2) throw new Error("&inspect-methods expected 2 arguments");
+  if (obj instanceof CalcitTrait) {
+    console.log("\n&inspect-methods");
+    console.log(`Note: ${toString(note, true)}`);
+    console.log(`Value type: ${type_of(obj).toString()}`);
+    console.log(`Value: ${toString(obj, true)}`);
+    console.log("Method call syntax: `.method self p1 p2`");
+    console.log("  - dot is part of the method name, first arg is the receiver\n");
+    const names = obj.methods.map((m) => "." + m.value);
+    console.log(`Trait methods declared directly (no impls): ${names.length}`);
+    console.log(`\nAll methods (unique, high → low): ${names.length}`);
+    console.log("  " + names.join(" "));
+    console.log("\n");
+    return obj;
+  }
   let pair = lookup_impls(obj);
   if (pair == null) {
     throw new Error(`&inspect-methods cannot resolve impls for: ${toString(obj, true)}`);
   }
   let impls = pair[0];
-  let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple;
+  let reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple || obj instanceof CalcitStruct || obj instanceof CalcitEnum;
 
   console.log("\n&inspect-methods");
   console.log(`Note: ${toString(note, true)}`);
@@ -2054,7 +2082,7 @@ export function _$n_inspect_methods(obj: CalcitValue, note: CalcitValue): Calcit
 
   let ms = _$n_methods_of(obj);
   console.log(`\nAll methods (unique, high → low): ${ms.len()}`);
-  console.log("  " + (Array.from(ms.items()) as string[]).join(" "));
+  console.log("  " + Array.from(ms.items()).map((m) => toString(m, false)).join(" "));
   console.log("\n");
 
   return obj;
@@ -2078,7 +2106,7 @@ export function _$n_trait_call(traitDef: CalcitValue, method: CalcitValue, obj:
     throw new Error(`&trait-call cannot resolve impls for: ${toString(obj, true)}`);
   }
   const impls = pair[0];
-  const reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple;
+  const reverse = obj instanceof CalcitRecord || obj instanceof CalcitTuple || obj instanceof CalcitStruct || obj instanceof CalcitEnum;
   let idx = reverse ? impls.length - 1 : 0;
   while (reverse ? idx >= 0 : idx < impls.length) {
     const impl = impls[idx];