@calcit/procs 0.12.53 → 0.12.55

package/RFCs/04-16-wasm-data-structures.md

@@ -214,4 +214,4 @@ List 在 Calcit 中是持久化数据结构（`Vector(Vec)` 或 `TernaryTreeList
 
 - 可行性评估: `rfc/04-15-wasm-compilation-feasibility.md`
 - 优化目录: `rfc/04-15-type-directed-optimization-catalog.md`
-- 用法文档: `docs/wasm-codegen.md`
+- 内部验证说明: `scripts/wasm-validation.md`

package/RFCs/07-26-agent-docs-and-evaluation-rfc.md

@@ -0,0 +1,33 @@
+# RFC: 结构化文档上下文与 Agent 工具链评估
+
+状态：Draft
+日期：2026-07-26
+关联：`07-19-doc-knowledge-index-rfc.md`、`07-26-agent-machine-protocol-rfc.md`
+
+## 1. 文档仍是结构化事实
+
+Markdown frontmatter、heading 与 snapshot definition metadata 都是可解析的树形数据。文档系统应保持 Markdown 可读、Git 可管理，同时从它们派生可删除重建的索引；不要求文档退化成纯文本检索，也不把 cache 当事实来源。
+
+为每个 definition 自动派生：
+
+```text
+calcit://definition/<namespace>/<name>
+```
+
+节点包含 doc/schema/examples/tags。Markdown 的 `id`、`parent`、`related`、`requires`、`leads_to`、`code_refs` 负责概念入口与精选关系，不要求作者手工列举全部 API。
+
+每个 heading 派生 section node，使用稳定 slug、内容 hash、层级、正文范围、代码块类型和 definition refs。这里的“范围”仅用于读取当前 Markdown section；源码定位仍遵循 definition/tree selector，而不是行号。
+
+## 2. 统一 frontmatter 与默认检索范围
+
+前端搜索、知识图和校验必须复用同一个版本化 frontmatter parser。逐步校验必填/enum、duplicate ID、dangling edge、scope、可解析 code refs 与可执行的 current 示例；旧文档可兼容读取，再分阶段变严格。
+
+默认 `cr docs search` 只覆盖 current guide/reference 与 definition metadata。RFC、草稿与 `editing-history/` 必须显式带 scope 才进入结果，避免历史语法污染 Agent 上下文。
+
+## 3. 可重复的 Agent 基准
+
+`yarn check-agent-interface` 作为真实 CLI 进程测试，至少记录：成功率、工具调用数、stdout bytes/token、无效命令、重定位/语法重试、修改后回归数和耗时。
+
+任务集覆盖：静态 type/method 查询；definition+schema+examples+docs 导航；重复 leaf 的指定 tree 编辑；新增 definition/import；schema 或 method 诊断；JS FFI intentional dynamic；changed verification；revision 冲突拒绝；从诊断到最小 example。
+
+每项 Agent API 改动必须同一任务集前后比较。是否引入 daemon/LSP、是否调整 context budget，均以这些测量数据决定。

package/RFCs/07-26-agent-machine-protocol-rfc.md

@@ -0,0 +1,102 @@
+# RFC: Agent 机器语义协议与按需解析
+
+状态：Draft
+日期：2026-07-26
+关联：`07-06-semantic-tree-navigation-rfc.md`、`07-26-static-semantic-analysis-rfc.md`
+
+## 1. 概要
+
+Calcit 的源码、定义元数据与编辑对象本来就是 Cirru EDN 树。Agent 接口应直接暴露这层语义，而不是退回到行号、正则或文本 patch。已有 `query context`、`query type`、`query type-at`、`analyze check-types/weak-types` 是第一批基础；本 RFC 固化它们共同需要的机器协议与演进方向。
+
+目标是让一次调用提供最小充分上下文，并让后续调用可验证、可继续展开，而不是输出完整 snapshot。
+
+## 2. 约束与非目标
+
+- 定位的主键是 `namespace/definition`、tree selector、subtree fingerprint 与 revision；数字 path 仅在当前 revision 内有效。
+- 不以 source line/column 为内部事实来源。若未来适配编辑器，行列只能由当前序列化文本临时映射。
+- 默认每次命令重新读取并解析所需 snapshot/module/doc。先依靠 Calcit 的启动速度，避免常驻进程带来的缓存失效、生命周期和维护成本。
+- 不以 LSP 为前置条件；只有重复解析已被基准证明确实成为瓶颈，且 LSP 的映射收益超过维护成本时，才评估薄适配层。
+- 本 RFC 不改变 snapshot 的 EDN 存储形式，也不引入 workspace。
+
+## 3. Typed result 与 JSON envelope
+
+每个命令先产生 typed result，再由 human/JSON renderer 输出；禁止从人类文本反向解析机器数据。
+
+```json
+{
+  "schema_version": 1,
+  "command": "query.context",
+  "revision": "opaque-content-hash",
+  "data": {},
+  "diagnostics": [],
+  "next": []
+}
+```
+
+规则：
+
+- `--format json` 时 stdout 只能是一个 JSON value；日志、tips 与 command echo 一律去 stderr；
+- `revision` 是不透明内容 hash，不承诺可读或跨项目一致；
+- 缺失信息用 `null` 或空集合表达，不依赖缺失字段或自然语言推断；
+- 有界列表携带 `truncated`、`next_cursor` 或可继续查询的 handle；
+- 保留兼容期 `--json`，但内部等价于 `--format json`；
+- 结果 schema 只能向后兼容地增加可选字段；破坏性变更升级 `schema_version`。
+
+## 4. 统一 Definition Descriptor
+
+query、docs、静态分析与 builtin fallback 应从同一只读描述视图组装结果：
+
+```json
+{
+  "id": "calcit.core/to-js-data",
+  "revision": "...",
+  "kind": "proc",
+  "source": { "scope": "core", "definition": "calcit.core/to-js-data" },
+  "schema": null,
+  "inferred_type": null,
+  "doc": "...",
+  "examples": [],
+  "tags": ["js-ffi"],
+  "dependencies": [],
+  "usages": [],
+  "diagnostics": []
+}
+```
+
+它是 provider 组合出的只读 view，不应变成 runtime 与 query 层互相依赖的巨型数据结构。builtin 与 source-backed definition 必须落入同一结果模型。
+
+## 5. 最小命令面
+
+优先完善以下只读命令，而不是新增多套近似查询：
+
+```bash
+cr capabilities --format json
+cr query context <ns/def> --budget 2500 --format json
+cr query type <type-or-definition> --format json
+cr query type-at <ns/def> --path code@3.2 --format json
+```
+
+`capabilities` 返回命令、参数/结果 schema、只读性、幂等性和支持的格式，使 Agent 不必加载所有 CLI help。
+
+`context` 默认只返回摘要、有限代码 fragments、schema/type、有限 examples、直接依赖/引用、关联文档、诊断和下一步 handle；`--profile understand|edit|debug|document` 仅是字段预算预设。
+
+`type-at` 应优先接受 semantic selector + expected fingerprint；数字 path 是兼容输入。查询只允许 parse、macro/preprocess 与静态 inference，不能因回答问题隐式执行 init function 或 FFI。
+
+## 6. 何时评估 daemon / LSP
+
+每次调用重新解析是默认架构。只有同时满足下列条件才进入实验：
+
+1. agent-interface 基准表明解析占主要延迟，且同一项目的连续查询不能由现有 cache 消解；
+2. daemon 能按 revision 可靠失效 snapshot、Git modules 与 docs；
+3. editor/LSP 映射不把行号变成新的事实来源；
+4. 有明确维护者承担协议兼容、进程恢复和跨平台测试。
+
+届时优先实现 `cr serve --stdio`，复用本 RFC JSON result；LSP/MCP 只是其上的薄映射。LSP 的 document symbol、references、hover、versioned diagnostics 与 workspace edit 可以借鉴，但内部身份仍是 definition/tree 语义。
+
+## 7. 验收
+
+- JSON stdout 可由 `JSON.parse` 直接解析，且版本、命令、revision、data、diagnostics 一致；
+- Agent 能用一次 `context` 和一次可选展开完成一个 definition 的理解；
+- 对相同 revision 的重复只读调用结果稳定；
+- `yarn check-agent-interface` 覆盖并记录耗时、stdout bytes、失败原因；
+- 性能数据而非直觉决定是否开始常驻服务或 LSP。

package/RFCs/07-26-safe-structured-editing-rfc.md

@@ -0,0 +1,66 @@
+# RFC: 可验证的结构化编辑与受影响范围检查
+
+状态：Draft
+日期：2026-07-26
+关联：`07-06-semantic-tree-navigation-rfc.md`、`05-12-program-diff-rfc.md`、`07-26-agent-machine-protocol-rfc.md`
+
+## 1. 原则
+
+Calcit 的编辑对象是 EDN tree，不是文本行。`cr edit` / `cr tree` 的安全性应来自 revision、semantic selector、subtree fingerprint、preview 与原子写入；不应把行号 patch 作为主工作流。
+
+数字 path 依然有价值，但只代表某一个 snapshot revision 下的瞬时坐标。任何会改变同级节点的操作后，调用方必须重新查询或使用 selector/fingerprint。
+
+## 2. 单操作契约
+
+修改类命令逐步支持：
+
+```bash
+--dry-run
+--expect-revision <opaque-hash>
+--format json
+--check-after
+```
+
+目标至少可表达 `definition ID + selector + expected subtree fingerprint`。revision 或 fingerprint 不匹配时拒绝写入，返回当前 revision 与候选节点；不做猜测性修改。
+
+dry-run 返回语义 diff、计划写入、受影响 definitions 和 diagnostics。`--check-after` 先从 parse/schema/preprocess 的最小受影响范围开始，而不是隐式运行所有 target。
+
+## 3. 多操作 transaction
+
+新增：
+
+```bash
+cr edit transaction --file changes.cirru --dry-run --format json
+```
+
+第一版 transaction 以 Cirru EDN 为主输入：外层 list 中，每个内层 list 是一条完整的 `edit`、`tree` 或 `config` 参数序列；`--code` 后可以直接嵌入 `quote` AST 节点，不需要把 Calcit 代码转义成字符串。JSON argument lists 仅作为兼容机器输入保留。这样不复制子命令的参数与校验语义；后续只有在 operation-level precondition 确有需要时，才在兼容此格式的基础上增加 typed operation record。
+
+transaction 可包含 tree replace、definition/import/config 改动；整体通过 `--expect-revision` 携带 snapshot precondition。执行顺序：
+
+1. 读取一次 snapshot 并计算 revision；
+2. 验证所有 precondition；
+3. 在内存副本应用全部操作；
+4. 校验 snapshot/Cirru/schema，预处理受影响 definition；
+5. 生成 semantic diff；
+6. dry-run 停止，或写同目录临时文件、flush、原子 rename；
+7. 返回新 revision、每个 operation 的结果和 diagnostics。
+
+任何失败都不修改原 snapshot。输出保存 operation ID，方便 Agent 精确重试。
+
+当前实现进度（2026-07-28）：已加入 `cr edit transaction` 第一版，以可直接嵌入 quoted code 的 Cirru EDN argument lists 为主格式，同时兼容 JSON；支持 `--dry-run`、snapshot `--expect-revision`、human/JSON 输出、同目录 staging、最终 revision 复核与原子 rename。子命令仍作用于 staged snapshot，因此沿用已有 `edit/tree/config` 校验；失败与 stale revision 不写原文件。operation-level precondition、semantic diff 与 `--check-after` 留待后续阶段。
+
+## 4. 受影响范围验证
+
+```bash
+cr analyze verify-changed --format json
+```
+
+它读取 Git diff 或最近 transaction result，基于 usages、call graph、schema dependency 找到直接修改项与调用者；执行可信的静态检查，并区分 `executed`、`recommended`、`not_run`。JS/IR/WASM 与全量测试先作为推荐项，避免从不可靠图自动宣称“已全覆盖”。
+
+## 5. 验收
+
+- stale revision 与 subtree mismatch 永不覆盖新内容；
+- 失败 transaction 不改变文件；
+- 成功写入可恢复地原子完成并返回新 revision；
+- semantic diff 以 definition/tree 变化表达，而非整文件文本噪音；
+- 并发 revision、重复 leaf、批量 import 与检查失败均有回归测试。

package/RFCs/07-26-static-semantic-analysis-rfc.md

@@ -0,0 +1,105 @@
+# RFC: 静态语义发现、类型证据与结构化诊断
+
+状态：Draft
+日期：2026-07-26
+关联：`03-05-function-schema-dual-track-rfc.md`、`07-26-agent-machine-protocol-rfc.md`
+
+## 1. 目标
+
+让人和 Agent 都能在不运行项目入口的条件下，获得 definition 或子树的可信静态信息：类型、method、trait、字段/variant、依赖证据与诊断。重点是置信度与边界清晰，不是把动态语言伪装成全静态语言。
+
+## 2. 静态查询
+
+```bash
+cr query type :number --format json
+cr query type ':: :list :number' --format json
+cr query type app.schema/Person --format json
+cr query type-at app.main/f --path code@3.2 --format json
+```
+
+返回 canonical type、可用 methods 与其 impl 优先级、schema/推断证据，以及可用时的 fields、enum variants、constructors、trait 和 examples。`type-at` 返回 inferred/expected type、lexical bindings、method candidates、evidence、definition revision 和 diagnostics。
+
+处理只允许加载与预处理静态 metadata，不执行 init function。必须执行才能知道的信息明确返回 unknown/diagnostic，不得静默回退到 runtime。
+
+## 3. 置信度与动态边界
+
+工具必须区分：
+
+- `proven`：schema 或静态规则已证明；
+- `partial`：信息只覆盖一部分结构；
+- `intentional-js-ffi` / `intentional-macro`：设计上允许的动态边界；
+- `unresolved`：应补 schema 或推断规则；
+- `unknown`：当前没有足够静态证据；
+- `failed`：静态处理本身失败。
+
+`:dynamic` 是“允许任意 Calcit 值”及“未知或放弃静态约束”的唯一语义。`:any` 是旧版本遗留的同义写法；解析时可兼容识别，但 schema、生成代码、文档与诊断输出都应迁移为 `:dynamic`。`check-types` 与 `weak-types` 不得把未识别 definition 或历史 `:any` 计为 full。
+
+同质 collection/ref、命名 struct/enum、函数参数/返回/泛型/where/rest 以及 callback variance 应尽可能保留类型信息；真正的 global state、JS FFI、宏边界和异构值可保持明确的 dynamic。
+
+### 3.1 多态能力的分层
+
+“暂时不知道类型”不是多态。多态必须保存调用位置之间可以验证的关系，不能用多个互不相关的 `:dynamic` 代替：
+
+| 需求 | 类型表达 | 静态收益 |
+|---|---|---|
+| 参数与返回值保持同一类型 | `:generics $ [] 'T`，在 `:args`/`:return` 复用 `'T` | 调用点绑定和返回类型替换 |
+| 只要求值具有某些能力 | `'T` 加 trait `:where` bounds | method 候选校验与静态 specialization |
+| 容器保持同质元素关系 | `:: :list 'T`、`:: :map 'K 'V`、`:: :ref 'T` | element/get/callback 类型继续传播 |
+| 数据结构携带类型参数 | generic `defstruct` / `defenum` 的 applied type args | 构造、字段、variant payload 与 match 保持一致 |
+| 回调的参数/返回关系 | 完整 `:: :fn`，保留 generics、rest 与 variance | 高阶函数调用检查，不把 callback 降为 `:fn`/`:dynamic` |
+| 有限异构分支 | 命名 `defenum`，可空值用 `:: :optional T` | 穷举 variant/payload 检查 |
+| 库声明、应用为 entry 选择一个全局类型 | `deftype-slot` / `:type-slots` entry 配置 | 跨编译单元注入；不是 per-call parametric polymorphism |
+
+当前不引入通用 union/intersection 类型。已知的有限分支优先用 enum，nil 分支用 optional；只有开放世界输入、无法建模的 FFI/global state 或宏边界使用 `:dynamic`。Bare `:list`、`:map`、`:ref` 及 `:fn` 只保留外形，不能表达元素、状态或 callback 之间的多态关系，因此 coverage 最多为 partial。
+
+泛型变量必须显式列在 `:generics`，`where` 只能约束已声明变量；applied struct/enum type args 必须满足 arity 与 where bounds。无法绑定的 TypeVar、dynamic callback slot 或 dynamic receiver 不得伪装成成功 specialization：分析结果必须保留 unresolved evidence，运行时兼容路径可以继续，但 Agent 应看到静态收益已经丢失。
+
+### 3.2 Dynamic debt 的 Agent 引导
+
+分析日志只在显式静态分析和 opt-in method warning 中出现，避免普通运行持续刷屏：
+
+- `analyze check-types` 有 partial/none 时产生 `W_TYPE_COVERAGE_GAPS`，并提示继续运行 scoped `weak-types`；
+- `analyze weak-types` 对 unresolved dynamic 产生 `W_DYNAMIC_TYPE_DEBT`，每个 occurrence 返回 `impact` 与 `suggestion`；
+- `--warn-dyn-method` 保留精确调用点 warning，用于发现 dynamic receiver 阻止 trait/core method specialization 的位置；
+- `intentional-js-ffi` 仍可见但不算 unresolved，提示在进入 typed code 前 validate/convert；
+- `:any` 输入按 dynamic debt 处理，输出和修复建议统一写 `:dynamic`。
+
+建议必须按关系给出修复方向，而不是机械地要求“给 dynamic 随便换一个类型”：同一类型关系用 TypeVar，能力约束用 trait/where，同质容器保留 type arg，有限异构值建模为 enum，真正边界才保留 dynamic。
+
+## 4. CalcitDiagnostic
+
+所有 parse、snapshot、macroexpand、preprocess、type-check、codegen、runtime 错误与 warning 逐步收敛到同一结构：
+
+```json
+{
+  "code": "E_METHOD_NOT_FOUND",
+  "phase": "preprocess",
+  "severity": "error",
+  "message": "...",
+  "location": {
+    "definition": "app.main/f",
+    "path": "@3.2",
+    "selector": "path ...",
+    "fingerprint": "..."
+  },
+  "expected": [],
+  "actual": null,
+  "related": [],
+  "fixes": []
+}
+```
+
+`code` 稳定，`message` 可改善；location 的 path 是临时坐标，selector/fingerprint 才是重定位依据。`.calcit/error.cirru` 与 JSON CLI 从同一诊断模型渲染。fix 只能描述可预览的结构化 edit，不能静默写入。
+
+## 5. 命令与验收
+
+逐步提供：
+
+```bash
+cr --check-only --format json
+cr query diagnostics --format json
+cr analyze check-types --format json
+cr analyze weak-types --intent unresolved --format json
+```
+
+验收包括：稳定 diagnostic code/phase、expected/actual 为结构数据、`type-at` 不执行程序、故意 FFI dynamic 不被误报、`:any` 输入 canonicalize 为 `:dynamic`、泛型/where/callback/container 中的 dynamic 能说明丢失的多态关系，以及正常/未知/显式 schema 分支的回归测试。

package/RFCs/07-28-git-module-store-rfc.md

@@ -0,0 +1,59 @@
+# RFC: Git 模块解析与本地内容寻址存储
+
+状态：Draft
+日期：2026-07-28
+关联：`docs/run/load-deps.md`
+
+## 1. 决策
+
+Calcit 暂不提供 registry，也不引入 workspace。模块的发布、获取与版本身份继续以 Git repository + ref/commit 为基础；模块仍以目录形态提供 `calcit.cirru`、文档与可选 Rust 动态库构建输入。
+
+依赖声明应优先使用发布 tag；tag 是可复现安装、兼容性沟通与 CI 的最佳实践。允许使用分支名以支持开发中的模块，但分支是可变引用：每次安装或更新都应显示其解析到的具体 commit，不能把“当前分支头”当作稳定版本身份。
+
+依赖图中同一模块只能选择一个版本：解析多个约束时统一选择最高版本，并对不同声明或无法严格满足的约束输出 warning，说明最终选中的 ref/commit 与受影响依赖。由于 namespace 是全局语义空间，不支持同项目多版本并存或 Cargo 式依赖重命名隔离。
+
+## 2. 问题
+
+直接把每个项目依赖完整 clone 到全局 modules 目录会造成重复体积；但单纯的 archive cache 不适合需要文档浏览、Git 状态检查、`build.sh` 和 Rust dylib 的模块。目标是在保留目录体验和 Git 路径的前提下，获得类似 pnpm 的去重。
+
+## 3. 两层本地布局
+
+建议将实现分为不可变 store 与项目可见链接：
+
+```text
+~/.config/calcit/store/git/<content-id>/     # 完整模块目录，按 resolved commit 内容去重
+<project>/.calcit/modules/<module-name>/     # 指向 store 的符号链接或平台等价链接
+```
+
+`content-id` 至少由 canonical repository URL、resolved commit、submodule 状态与必要构建输入版本组成。tag 或分支名只用于解析；store 身份始终以其解析后的 commit 为准。链接目标是完整目录，因此 snapshot、docs、native source、已构建产物与诊断文件仍能按现有路径读取。
+
+项目 snapshot 的 `:modules` 可继续使用模块目录路径。链接层只解决本地寻址和项目隔离，不改变模块的目录接口。
+
+## 4. 解析与 native 模块
+
+当前不引入 `calcit.lock`。`deps.cirru` 是唯一的依赖声明与解析来源；`caps` 每次按其 tag/branch 解析依赖图并选择统一最高版本。命令结果应记录 canonical Git URL、声明的 tag/branch、实际 resolved commit、版本选择 warning 和完整性信息，方便 CI 日志与问题排查。对于 branch 依赖，更新应明确提示其从哪个 commit 前进到哪个 commit。
+
+Rust dylib 不是 store 的例外：其 source 与 `build.sh` 仍在模块目录中。产物必须按 target triple、Calcit ABI/version、Rust toolchain 或 build-input hash 分桶，不能跨不兼容环境复用。构建前展示将执行的脚本、来源与 hash；失败信息关联到具体 module revision。
+
+## 5. caps 命令演进
+
+在保留 `caps`、`outdated`、`status`、`reset` 的基础上，逐步增加：
+
+```bash
+caps add <git-url-or-org/repo>@<constraint>
+caps remove <module>
+caps tree
+caps why <module>
+caps update [module]
+caps verify
+```
+
+`caps status` 区分 store 完整性、项目链接、当前 `deps.cirru` 解析结果、版本选择 warning、native 产物兼容性和用户手工修改。不可变 store 不接受直接编辑；开发依赖使用明确的 path/checkout override，而不是污染共享内容。
+
+## 6. 非目标与验收
+
+- 不建设中心 registry、账号、发布服务、lockfile 或语义版本多版本安装；
+- 不支持 workspace，也不让多个版本进入同一 namespace 空间；
+- 不把模块压缩成失去 docs/native source 的 blob。
+
+验收：两项目共享同一 resolved revision 只保存一份内容；项目链接可独立重建；版本不一致时选择最高版本并输出可读 warning；不同 native ABI/target 不会错误复用产物；原有目录模块加载与文档命令保持兼容。