@calcit/procs 0.13.27 → 0.13.29

package/RFCs/08-21-static-type-system-evolution-roadmap.md

@@ -0,0 +1,315 @@
+# RFC：Calcit 静态类型系统长期演进路线
+
+状态：Draft
+
+日期：2026-08-21
+
+## 摘要
+
+Calcit 长期继续借鉴 Rust 与 MoonBit：使用名义数据类型、Enum、Option/Result、trait、穷尽模式
+匹配、局部推断、明确 unsafe/FFI 边界和工具链一体化，逐步提高“typed core 中静态通过即不会发生
+普通类型错误”的可信度。
+
+这里的“借鉴”不是复制语言表面。Calcit 保留持久化数据、GC/运行时值模型、Snapshot、热更新和
+多后端特点；不因为 Rust 成功就引入与当前 value model 不相容的 borrow checker，也不因为 JS
+生态复杂就复制 TypeScript 的结构类型、union 与 overload。
+
+路线优先级是：先堵住精度静默丢失和 FFI unsafe 边界，再完善控制流与局部推断，然后根据真实
+抽象需求扩展 trait。每一步必须通过生态 quality baseline 与真实消费者回归渐进落地。
+
+## 当前基础
+
+Calcit 已有：
+
+- primitive、List/Map/Set/Ref/Fn 等参数化 schema；
+- 名义 Struct、Enum、Trait、Impl 及定义值类型；
+- 显式 generics、TypeVar、`:where` trait constraints；
+- `Option<T>`、`Result<T,E>`、`Unit`、`JsNullish<T>`；
+- applied generic Struct/Enum；
+- bottom-up 推断和调用点泛型绑定；
+- `check-types`、`weak-types`、`quality` 和结构化诊断；
+- JS/native/WASM 等后端前的统一预处理。
+
+这些足以支持一条渐进增强路线，不需要重做类型 AST 或切换到完全不同的语言家族。
+
+## 需要解决的核心矛盾
+
+### `Dynamic` 同时表示意图和失败
+
+当前 `Dynamic` 既可以表示维护者明确选择的开放边界，也可能来自：
+
+- 缺少容器参数；
+- 无法绑定的 TypeVar；
+- 未解析 type slot；
+- 旧 Snapshot 或未知 schema；
+- 推断无法继续时的兼容 fallback。
+
+后续 `weak-types` 虽能找回部分证据，但类型检查阶段已经把“允许任意值”和“我们还不知道”混在
+一起。长期应分离 intentional Dynamic 与内部 Unknown/Unresolved。
+
+### 静态正确与后端正确尚未完全闭环
+
+纯 Calcit、JS FFI、native dylib 和内部 WASM 验证后端承担的保证不同。逻辑 schema、target
+capability、ABI transport 和真实宿主值不能被一个 `matches` 结果混成同一层。
+
+长期模型应是：
+
+```text
+source schema
+  -> inference/type checking
+  -> capability/target validation
+  -> backend contract/ABI validation
+  -> runtime tests for external facts
+```
+
+每层只增加证据，不让 runtime fallback 反过来伪装成静态推断成功。
+
+### 大型框架缺少低摩擦的类型表面
+
+Editor/Respo 类项目中的 Dynamic 集中在 store、component props、dispatch、effect callback 和
+生命周期。这既有历史债务，也说明当前显式 schema 在高阶 UI 代码中成本偏高。解决方案优先是
+改进框架公共类型、局部推断和诊断，而不是直接放宽为结构类型。
+
+## 借鉴范围
+
+### 从 Rust 借鉴
+
+- Enum/Struct 作为主要领域数据模型；
+- Option/Result/Unit/Never 的明确控制流含义；
+- match 穷尽性和不可达分支诊断；
+- trait/impl coherence 与明确的泛型约束；
+- unsafe 是小而可审计的边界；
+- 错误带 expected/actual、来源和可执行修复路径。
+
+暂不借鉴所有权/借用语义。Calcit 的 persistent collection、runtime object、热更新和多后端模型
+与 Rust 资源生命周期不同。若未来需要文件句柄、socket、WASM linear resource 等线性能力，
+应先以独立 resource/effect RFC 证明需求，不把 borrow checker 作为类型系统成熟度指标。
+
+### 从 MoonBit 借鉴
+
+- 局部、可预测的类型推断，减少重复 annotation；
+- 名义 ADT、pattern matching、trait 与泛型的统一开发体验；
+- 编译器、formatter、test、doc、package/CI 作为同一工具链；
+- 对不同后端保持共享类型语义，并在后端边界明确报告限制；
+- 快速反馈和高质量诊断优先于追求最大理论表达力。
+
+不复制其他语言的具体语法或包格式。Calcit 的 Cirru/Snapshot 是自己的事实来源，演进必须保留
+结构编辑和可迁移性。
+
+## 设计不变量
+
+未来类型功能必须满足：
+
+1. 普通 typed core 不因 backend 不同获得不同的类型匹配结果；
+2. FFI metadata、feature/effect 和 ABI transport 不污染普通 nominal type identity；
+3. 无法证明时保留 Unknown evidence，不伪装为成功 specialization；
+4. explicit Dynamic 永远可被 query/quality 解释其 intent；
+5. 新规则先进入 preprocess/analyze，不向 interpreter 增加无关运行时特判；
+6. 诊断包含 definition、path、expected、actual、evidence loss 和修复建议；
+7. 新严格规则通过 baseline/entry policy 渐进启用；
+8. native 与 JS 是公开语义后端，内部 WASM 验证后端不静默返回假结果。
+
+## 路线 A：精度与 sound boundary
+
+### A1. `Unknown/Unresolved` 内部状态
+
+内部增加“不足以完成推断”的 evidence 状态，但不一定立即成为用户可写类型：
+
+- 缺少 generic args；
+- unbound TypeVar；
+- unresolved type slot；
+- 未知 imported schema；
+- 分支无法合并。
+
+它不能像 Dynamic 一样双向匹配所有类型。兼容模式可在最终边界降为 Dynamic，同时产生稳定诊断；
+strict policy 下阻止公开 API、typed decoder 和 FFI 强类型 assertion 使用 unresolved value。
+
+### A2. 显式 Dynamic intent
+
+逐步让 intentional boundary 可由 schema/metadata 表达原因，例如 js-ffi、framework state、macro、
+open data。quality 仍显示这些位置，但与 unresolved 使用不同策略。不要通过注释文本或文件路径
+猜测 intent。
+
+### A3. unsafe inventory
+
+`unsafe-coerce`、raw host operation、native ABI assertion 进入统一 inventory。目标不是禁止 unsafe，
+而是做到 Rust 式“边界很小、调用原因可查、测试责任清楚”。
+
+## 路线 B：控制流与代数数据
+
+### B1. 穷尽性与 Never
+
+- named Enum match 检查所有 variants；
+- duplicate/unreachable pattern 诊断；
+- `Never` 表示必然终止、raise、todo trap 等无返回路径；
+- 分支合并理解 Never，不要求用 Dynamic/nil 填补；
+- Option/Result helper 与 match 保留 payload 精度。
+
+### B2. Narrowing
+
+只对可证明的语言结构做 flow-sensitive narrowing：
+
+- Option/Result/Enum variant match；
+- nil/nullish presence check；
+- predicate 若有明确 compiler-known contract，可收窄对应分支；
+- assertion 只在成功分支增加 evidence。
+
+不引入任意 JavaScript property test 驱动的结构化 narrowing，也不从字符串比较推导复杂 union。
+
+### B3. Data decoding
+
+将严格 Cirru EDN decoder、Map-to-Struct 和未来 JS data decoder 统一建立在 closed data shape 上。
+Dynamic、裸容器和 unresolved slot 不能生成一个看似安全的 decoder。
+
+## 路线 C：局部推断与泛型体验
+
+### C1. 双向检查
+
+在已有 bottom-up inference 上增加 expected-type 向下传播，优先覆盖：
+
+- lambda 作为已知 Fn 参数；
+- Struct/Enum constructor payload；
+- Option/Result method chain；
+- collection literal 的元素/键值；
+- callback return；
+- match branch expected result。
+
+目标是减少重复 annotation，而不是进行不可预测的全程序推断。
+
+### C2. 泛型诊断
+
+泛型失败需要解释：
+
+- 哪个参数绑定了 TypeVar；
+- 哪两个约束冲突；
+- outer shape 是否仍被保留；
+- 是否因 Dynamic/Unknown 丢失 specialization；
+- 可选择补 annotation、泛型或 trait bound 的具体位置。
+
+### C3. Trait coherence
+
+先稳定 impl identity、conflict、selection 和 where-bound 诊断。generic trait、associated type 或
+higher-kinded abstraction 只有同时满足以下条件才进入独立 RFC：
+
+- 至少三个非 FFI 的真实生态用例；
+- 不需要结构化自动满足；
+- 能定义明确 coherence/overlap 规则；
+- native/JS 语义和 query evidence 一致；
+- 不显著恶化常见代码的推断耗时与错误可读性。
+
+## 路线 D：框架与 effect
+
+### D1. 框架类型表面
+
+先在 Respo/Editor 试点：
+
+- 标准化 Store、Reel、Dispatch、Component Props、Effect Callback；
+- 用 generic Struct/Enum/Fn 保留 state/action 关系；
+- framework intentional boundary 只留在入口和生命周期 adapter；
+- 业务 component 内不依赖全局 Dynamic。
+
+如果固定字段 props 的书写成本仍然过高，可以讨论 record/row ergonomics，但必须保留封闭字段、
+名义导出和清晰错误；不直接采用 TypeScript 开放 object type。
+
+### D2. Feature、effect 与 resource 分离
+
+`:features` 表示实现体允许使用的 capability；未来 `:effects` 若存在，表示可传播的 effect；resource
+若需要线性/生命周期约束，则是第三个独立概念。三者不能都塞进 Fn equality 或用一个 set 同时解释。
+
+优先通过 effects graph、query 和 lint 积累用例，再决定是否进入函数类型。
+
+## 兼容与采用
+
+### Strict policy，而非全局硬切换
+
+建议 entry/project policy 逐步提供：
+
+- compatible：允许历史 Dynamic fallback，输出 evidence；
+- ratchet：不得比提交的 quality baseline 增加债务；
+- strict：公开 API、decoder、FFI typed boundary 不允许 unresolved；
+- core：Calcit core/stdlib 使用的更强内部门禁。
+
+名称可以在实现 RFC 中调整，但含义必须清楚。新模块从 strict/zero baseline 开始，历史应用使用
+ratchet，避免每次类型增强引发全生态同步重写。
+
+### 生态验证集
+
+类型系统改动不能只通过 compiler fixtures。至少维护：
+
+- 小型纯库：bisection-key、memof；
+- 高覆盖 FFI：js-ffi、calcit-wss；
+- native dylib：http/wss/fetch 类项目；
+- 框架：recollect、Respo workflow；
+- 大型应用：Editor、网站；
+- native 与 JS 生成/运行；
+- 内部 WASM subset regression。
+
+每次 release 记录 quality baseline delta、诊断变化、后端矩阵和至少一个关键消费者结果。
+
+## 明确暂缓的方向
+
+- 通用 union/intersection/conditional types；
+- TypeScript 式 structural object satisfaction；
+- 任意 overload resolution；
+- 由 JS FFI 单独驱动 generic trait/associated type；
+- 没有资源用例支撑的 borrow checker；
+- 全程序隐式 HM inference；
+- 把 feature/effect/target 混入普通 Fn 匹配；
+- 为每个后端维护不同的核心类型规则。
+
+暂缓不等于永久拒绝；重新提出时必须带真实用例、迁移成本、诊断设计和多后端验证。
+
+## 实施顺序
+
+### Phase 1：保证边界诚实
+
+- 区分内部 Unknown 与 intentional Dynamic；
+- unresolved type slot/generic 不再静默 specialization；
+- unsafe/FFI inventory；
+- quality baseline 在参考模块落地。
+
+当前已交付的第一步是把未绑定 `*type-slot` 从 `Dynamic` 中分离为 `weak-types` 的
+`unresolved-type-slot` evidence：`check-types` 将它降为 partial，`analyze quality` 将它计入既有
+`unresolved` budget，机器协议以 v3 公开稳定 path、impact 与修复建议。entry 明确选择
+`:dynamic` 时仍会报告为 `intentional-type-slot-dynamic`，不会伪装成已证明的 concrete binding。
+这保持了旧项目的运行时兼容；hard error、内部 `Unknown` 类型和 generic binding evidence 仍是后续
+增量，不能把本步误解为类型匹配已经收紧。
+
+### Phase 2：提高 typed core 表达力
+
+- Enum exhaustiveness、Never 和 narrowing；
+- lambda/constructor/callback 的双向检查；
+- 泛型 binding evidence 与冲突诊断。
+
+### Phase 3：框架试点
+
+- Respo/Editor 的 typed state/props/dispatch；
+- 观察是否需要 record ergonomics、generic trait 或 effect contract；
+- 只有数据证明后才提交独立核心扩展 RFC。
+
+### Phase 4：稳定性承诺
+
+- strict policy 成为新模块默认；
+- pure typed core 的 runtime type failure 建立 compiler bug 分类与 regression test；
+- FFI/runtime/ABI 失败有独立 contract 错误和验证矩阵；
+- 类型与诊断机器协议遵循兼容版本策略。
+
+## 成功标准
+
+1. 新模块不使用 Dynamic 也能自然表达常见业务和 callback 数据流。
+2. intentional Dynamic 与 inference failure 在 query/quality 中完全可区分。
+3. pure typed core 出现普通类型 runtime failure 时可以稳定归类为 compiler defect。
+4. Editor/Respo 的 Dynamic 主要收缩到框架入口，而不是遍布业务 definition。
+5. FFI 类型通过后仍由 target/contract tests 提供宿主证据，错误能够指回 Calcit binding。
+6. 新类型特性不会让不使用它的程序改变 trait candidate 或 backend 行为。
+7. 生态升级使用 baseline ratchet，不再依靠一次性大规模改写。
+
+## 与既有 RFC 的关系
+
+- `02-18-language-theory-evolution-plan.md` 继续描述 law、语义分层和类型驱动诊断愿景；本 RFC
+  补充静态类型 sound boundary、推断、控制流和生态采用路线。
+- `07-26-static-semantic-analysis-rfc.md` 是 evidence/diagnostic 基础。
+- `08-05-systematic-nil-reduction-rfc.md` 是 Option/Result/Unit/Never 路线的具体迁移。
+- `08-18-calcit-typed-js-ffi-boundary-rfc.md` 和
+  `08-21-js-ffi-runtime-contract-validation-rfc.md` 负责宿主边界。
+- `08-21-type-quality-ci-adoption-rfc.md` 负责把类型演进安全地推入生态。

package/RFCs/08-21-type-quality-ci-adoption-rfc.md

@@ -0,0 +1,272 @@
+# RFC：Calcit 生态类型质量门禁与 CI 采用方案
+
+状态：Draft
+
+日期：2026-08-21
+
+## 摘要
+
+Calcit 已提供 `analyze check-types`、`analyze weak-types` 和原生 `analyze quality`，并支持按
+definition 保存 baseline。现在缺少的不是另一套统计脚本，而是一份跨模块的采用协议：什么是
+定位报告，什么是发布门禁；新项目与存量项目如何采用；baseline 如何审阅和收紧；静态通过后
+还需要哪些后端运行证据。
+
+本 RFC 规定：
+
+1. 类型质量门禁统一使用 `calcit analyze quality`，不得在各仓库自行拼 JSON 或补 JS 比较脚本；
+2. 新模块默认零容忍，存量模块提交按 definition 的 baseline 并只允许逐步收紧；
+3. 类型门禁只是 CI 的静态层，不能替代 native/JS/browser/dylib 的实际运行测试；
+4. 文档、模板、机器输出和 baseline 更新流程形成一条可追溯的生态规范。
+
+## 已有能力
+
+当前仓库已经具备：
+
+- `check-types`：统计 full/partial/none 类型覆盖；
+- `weak-types`：定位 schema/code 中的 Dynamic、nil/Optional 和其他弱类型证据；
+- intent 分类：区分 unresolved debt 与已知 FFI/framework boundary；
+- definition/path、impact、suggestion 等结构化定位信息；
+- `analyze quality`：以非零退出码阻止类型质量回归；
+- `--write-baseline` / `--baseline`：按 definition 保存预算，避免一处清债抵消另一处新增；
+- 单一 JSON envelope，适合 CI 保存和消费。
+
+概念指南见 `docs/type-guidance.md`，完整类库验收矩阵见
+`docs/run/library-quality.md`。本 RFC 不复制这两份 how-to，而是为整个生态规定采用和演进政策。
+
+## 问题
+
+### 工具存在，但采用方式不统一
+
+生态项目目前混合使用以下策略：
+
+- 只运行默认 entry；
+- 只执行 `--check-only`；
+- 分别调用 `check-types` / `weak-types`，但不根据退出码形成门禁；
+- 在 workflow 中用 shell、jq 或 JavaScript 自己比较统计数字；
+- 每次 CI 重新生成 baseline，等同于自动接受新债务；
+- 只生成 JS，不实际执行 Node/browser 测试。
+
+这些 workflow 表面都叫“type check”，实际保证不同，后续升级无法判断失败是新增债务、输出协议
+变化还是自定义脚本失效。
+
+### 类型覆盖率不是正确性证明
+
+类型 full 只说明声明和静态推断足够完整。它不能证明：
+
+- JavaScript import/export 在目标 runtime 中存在；
+- `unsafe-coerce` 的宿主值真的满足声明；
+- browser binding 没有在 Node entry 使用；
+- callback 参数、返回值和 exception 行为符合 FFI 契约；
+- native dylib 的 ABI 与 `cirru_edn` 版本一致；
+- 已生成 JS 与当前 `@calcit/procs` runtime 相容。
+
+因此静态质量与后端契约测试必须分别保留，不能用一项绿色 check 代表全部质量。
+
+## 统一质量层级
+
+每个模块在 README 或维护文档中声明当前采用层级：
+
+| 层级 | 必需证据 | 适用范围 |
+| --- | --- | --- |
+| Q0 Snapshot | `edit format` 无 diff、`--check-only` | 所有项目 |
+| Q1 Type ratchet | `analyze quality` 零容忍或已审阅 baseline | 所有维护中的模块 |
+| Q2 Public API | 公开 API full 优先、examples/docs/test entry | 可复用类库 |
+| Q3 Backend contract | 实际执行声明支持的 native/JS/browser/dylib 路径 | FFI、workflow、应用 |
+| Q4 Consumer | 至少一个真实下游回归 | 核心库、编译器、关键基础模块 |
+
+层级是累积的。Q3 不能跳过 Q1，Q1 也不能声称已覆盖运行时正确性。历史项目可以从 Q0/Q1
+开始，不因一次迁移被迫达到 Q4。
+
+## 规范 CI
+
+### 安装与版本
+
+工具版本来自 `deps.cirru`：
+
+```yaml
+- uses: actions/checkout@v4
+- uses: calcit-lang/setup-cr@0.0.9
+```
+
+普通项目不在 workflow 重复填写 `version`。setup-cr 的详细契约由
+`08-21-setup-calcit-version-and-toolchain-contract-rfc.md` 规定。
+
+### Q0 + Q1 基础门禁
+
+新项目：
+
+```bash
+caps --ci
+calcit calcit.cirru edit format
+git diff --exit-code -- calcit.cirru
+calcit calcit.cirru --check-only
+calcit calcit.cirru analyze quality --format json
+```
+
+存量项目只把最后一行改为：
+
+```bash
+calcit calcit.cirru analyze quality \
+  --baseline config/calcit-quality.json \
+  --format json
+```
+
+`check-types` 与 `weak-types` 用于本地定位和 PR 解释，不再承担自定义退出逻辑：
+
+```bash
+calcit calcit.cirru analyze check-types --summary-only
+calcit calcit.cirru analyze weak-types \
+  --only schema-dynamic,unresolved-type-slot,code-dynamic \
+  --intent unresolved
+```
+
+CI 可以保存 JSON 报告，但不得解析若干子报告后自行发明总分。需要新的质量维度时，先扩展
+`analyze quality` 的版本化协议，再由所有项目统一升级。
+
+### Q2 公开 API
+
+可复用类库至少增加：
+
+```bash
+calcit calcit.cirru analyze check-examples --ns package.api
+calcit calcit.cirru docs format-md README.md --check
+calcit calcit.cirru docs check-md README.md --failures-only
+calcit calcit.cirru --entry test
+```
+
+没有 examples 且命令退出零不代表覆盖完成。公开 definition 必须由 runnable example 或明确的
+测试 entry 覆盖。公开 API 新增 `Dynamic` 时，即使 baseline 仍有余额，也要求 PR 说明它属于哪种
+边界、为什么不能使用泛型/trait/Enum/Option/Result。
+
+### Q3/Q4 后端与消费者
+
+- JS 模块：codegen 后实际运行 Node test；browser API 运行 headless browser smoke/contract test；
+- native dylib：build、复制实际 artifact、由目标 `calcit` 进程装载并调用；
+- 多 entry：逐一运行声明支持的 mode/target，不能只测 default；
+- 核心/基础库：记录至少一个真实消费者仓库、commit、entry 和命令。
+
+后端矩阵由项目显式维护，不能交给 setup-cr 自动猜测。
+
+## Baseline 治理
+
+### 首次创建
+
+```bash
+calcit calcit.cirru analyze quality \
+  --write-baseline config/calcit-quality.json
+```
+
+生成后必须人工审阅：
+
+- debt 是否确实属于当前项目，而非未加载依赖或错误 entry；
+- intentional FFI/framework 分类是否准确；
+- public API 的 Dynamic 是否可以先收窄；
+- baseline 中每个 definition 是否有负责人或迁移方向。
+
+审阅完成后将文件提交。CI 永远不能先 `--write-baseline` 再 `--baseline`。
+
+### 更新规则
+
+1. 一般 PR 只允许删除或降低 definition 预算；
+2. 新增债务需要独立说明，不与无关功能提交混在一起；
+3. 重命名/移动 definition 时，由工具提供可审阅迁移，不能整体重建以抹去历史；
+4. 编译器新增质量维度时，先输出 migration summary，再更新 baseline schema version；
+5. baseline 文件包含生成它的 quality schema version，不绑定机器绝对路径或时间戳；
+6. intentional boundary 也进入可见报告，只是不与 unresolved debt 使用同一失败策略。
+
+长期目标是让重点模块 baseline 归零，而不是永久维护一个“允许 Dynamic 的白名单”。
+
+## 文档体系
+
+避免同一命令在多个位置出现互相矛盾的解释：
+
+| 文档 | 职责 |
+| --- | --- |
+| `docs/type-guidance.md` | 如何选择具体类型、泛型、trait、Option/Result |
+| `docs/run/library-quality.md` | 可复制的本地与 CI 验收步骤 |
+| 本 RFC | 生态采用、层级、baseline 治理与演进政策 |
+| setup-cr README | 只说明工具安装和版本来源 |
+| 模块 README | 声明本项目达到的质量层级与特有后端矩阵 |
+
+新增质量能力时先更新机器命令和这张职责表，再更新模板；不把临时 shell/JS 脚本复制到多个
+仓库成为事实标准。
+
+## 生态推进顺序
+
+### 第一批：参考项目
+
+- `js-ffi`、`calcit-wss`：保持高类型覆盖，补 Q3 runtime contract；
+- `calcit-http`：为 native callback/options 建立显式 FFI 契约；
+- `bisection-key`：清理容器与泛型 Dynamic，验证存量 baseline 收紧流程；
+- `calcit.std`：作为零容忍或低 baseline 的类库模板。
+
+### 第二批：框架
+
+- `memof`、`recollect`、`respo-calcit-workflow`：先收敛 store、dispatch、callback schema；
+- 把确实属于框架开放边界的 Dynamic 标明 intent；
+- 避免每个应用重复声明同一套框架生命周期类型。
+
+### 第三批：大型应用
+
+- Editor 和网站项目先建立 baseline；
+- 以 namespace/definition 为单位收紧，不做一次性全量重写；
+- 优先处理全局 state、组件 props、effect callback 和跨模块公共 API。
+
+## 机器协议要求
+
+`analyze quality --format json` 应保持：
+
+- stdout 是单一 envelope；
+- stderr 只输出人类摘要和进度；
+- schema version 显式存在；
+- failure reason 区分当前债务、相对 baseline 的新增、baseline 过期和工具配置错误；
+- occurrence 包含 definition、namespace、path、kind、intent、impact、suggestion；
+- 退出码稳定区分 quality failure 与命令/解析失败。
+
+如果 GitHub annotations 或 SARIF 有明确需求，应由 `calcit` 原生输出或提供统一转换器。各项目不再
+自行实现一份脆弱的 JS parser。
+
+## 实施阶段
+
+### Phase 0：采用与模板
+
+- 将本 RFC、type guidance、library quality guide 互相链接；
+- 更新模块模板为 setup-cr 无 version + `analyze quality`；
+- 选取四个第一批项目记录 baseline/zero-tolerance 实践。
+
+### Phase 1：协议稳定
+
+- 固定 quality JSON 与 baseline schema version；
+- 补 baseline rename/move 和过期诊断；
+- 提供统一的 GitHub annotation/SARIF 输出时仍保持原生命令为事实来源。
+
+### Phase 2：后端契约接入
+
+- 将 JS FFI unsafe/coercion 和 native ABI 风险纳入质量维度；
+- quality summary 链接对应 Q3 测试，但不伪装成已执行 runtime test；
+- 重点模块逐步从 Q1 推进到 Q3/Q4。
+
+## 验收标准
+
+1. 新 Calcit module 不需要自写 JS 脚本即可阻止类型债务回归。
+2. 存量 module 的 baseline 不会因每次 CI 重建而自动放宽。
+3. CI 日志能明确区分 Snapshot、type quality、backend runtime 和 consumer regression。
+4. 至少四个参考项目采用同一套 Q0/Q1 命令，并记录各自 Q3 矩阵。
+5. 新增 quality 指标通过版本化协议进入生态，不要求所有仓库同时修改自定义 parser。
+6. `full` 类型覆盖不再被文档描述为 FFI/runtime 正确性的充分证明。
+
+## 非目标
+
+- 用单一分数比较不同规模项目；
+- 要求所有历史应用立即零债务；
+- 把 intentional FFI boundary 隐藏出报告；
+- 让 setup-cr 隐式执行项目测试；
+- 以静态门禁替代真实后端运行。
+
+## 相关资料
+
+- `docs/type-guidance.md`
+- `docs/run/library-quality.md`
+- `RFCs/07-26-static-semantic-analysis-rfc.md`
+- `RFCs/08-21-setup-calcit-version-and-toolchain-contract-rfc.md`
+- `RFCs/08-21-js-ffi-runtime-contract-validation-rfc.md`

package/RFCs/README.md

@@ -1,6 +1,6 @@
 # RFC 整理索引
 
-更新时间：2026-08-18
+更新时间：2026-08-21
 
 ## 目录原则
 
@@ -27,8 +27,8 @@
 | `04-15-wasm-compilation-feasibility.md`             | Active        | WASM 编译三条路径（解释器→WASM / AOT 子集 / WASM GC）的可行性评估。                       |
 | `04-16-wasm-data-structures.md`                     | Active        | WASM codegen 中 Tag/Record/Tuple 等数据结构的内存布局与编译策略。                         |
 | `05-31-generic-where-bounds-mfs.md`                 | Active        | 函数 schema 泛型 `:where` 约束的最小功能规格，先作为主链路开发基线。                      |
-| `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 函数调用方案。               |
+| `06-15-effects-graph-rfc.md`                        | Draft         | `calcit analyze effects-graph`：State/Transform/Effect 语义分解图与类型驱动 effect 标注路线。 |
+| `06-29-cr-exec-cli-builtins-rfc.md`                 | **Active**    | `calcit 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 延后）。 |
@@ -37,7 +37,6 @@
 | `07-26-safe-structured-editing-rfc.md`              | Draft         | revision/fingerprint 前置条件、事务编辑、语义 diff 与受影响范围验证。                                                  |
 | `07-26-agent-docs-and-evaluation-rfc.md`            | Draft         | 结构化文档上下文、默认检索范围和 Agent 接口基准。                                                                        |
 | `07-28-git-module-store-rfc.md`                     | Draft         | 保持 `deps.cirru` 与 Git 模块路径，以 tag 为最佳实践并使用 pnpm 式全局目录存储；不引入 registry、lockfile、workspace 或多版本。 |
-| `07-28-project-tooling-contract-rfc.md`             | Draft         | 在既有 `cr` 子命令上补强单项目工具契约，保持 EDN 树形事实来源。                                                        |
 | `07-28-persistent-tree-cursor-rfc.md`               | Draft         | `.calcit/` 本地状态、虚拟 cursor、region/marks/last-query、结构化 clipboard 与 path 迁移。                            |
 | `08-14-architecture-scaffold-rfc.md`                | Implemented   | Cirru EDN architecture graph、existing-definition reconciliation、atomic scaffold apply、work items 与多 Agent 分工边界。 |
 | `08-14-todo-placeholder-rfc.md`                      | Partial       | compiler-known `todo!`、`W_TODO` 与 native/JS/WASM 中止行为已落地；完整 Never/control-flow inference 后续实现。 |
@@ -45,6 +44,10 @@
 | `08-05-systematic-nil-reduction-rfc.md`              | Partial       | 类型驱动减少 nil：先拆分可省略参数与 nullable 值，再迁移至 Option/Result 并逐步收紧 typed code。                  |
 | `08-08-cross-backend-host-ffi-contracts-rfc.md`      | Draft         | 统一 JS/native/WASM/WASI 的逻辑 FFI 契约与诊断，ABI transport 保持 backend-specific；首个完整 shape consumer 为 JS/DOM。 |
 | `08-18-calcit-typed-js-ffi-boundary-rfc.md`           | Draft         | 在现有 Struct/Enum/Fn/trait 上补齐 JS capability gate 与 target validation；FFI metadata 不进入普通 trait 匹配和泛型推断。 |
+| `08-21-setup-calcit-version-and-toolchain-contract-rfc.md` | Draft       | 以 `deps.cirru` 为正常项目的唯一 Calcit 版本来源；只下载 `calcit`，并由 Action 提供 `cr` 兼容链接。 |
+| `08-21-type-quality-ci-adoption-rfc.md`               | Draft       | 统一使用原生 `analyze quality` 与按 definition baseline，定义生态 CI 层级并禁止各项目重复实现 JS 汇总脚本。 |
+| `08-21-js-ffi-runtime-contract-validation-rfc.md`     | Draft       | 在现有 typed JS FFI 声明之上增加 host guard、decoder、runtime contract tests 与 unsafe evidence。 |
+| `08-21-static-type-system-evolution-roadmap.md`       | Draft       | 借鉴 Rust/MoonBit 推进 Unknown/Dynamic 分离、穷尽性、局部推断、trait coherence 与框架类型化。 |
 
 ## 已执行的清理
 

package/editing-history/20260820-1704-repository-maintenance-review.md

@@ -0,0 +1,21 @@
+# Repository maintenance review
+
+- Verified TypeScript compilation, Rust clippy, and the full Rust test suite;
+  no safe dead-code removal was identified in the current codebase.
+- Reclassified the README module configuration example as `cirru.no-check`:
+  it is snapshot data, not runnable Calcit. This restores Markdown example
+  validation under the current required-Struct-field analysis.
+- Replaced the obsolete `cr config version` transaction smoke operation with
+  `edit doc`; project versions now belong in `deps.cirru` and are managed by
+  `caps version`, while the test still exercises a two-operation dry run.
+- Consolidated 47 overlapping cursor, module-cache, and release checkpoints
+  into `ARCHIVE.md`. The archive preserves durable behavior and directs readers
+  to the current operational documents; exact notes remain available through
+  Git history.
+- Updated history retention guidance so a completed, high-churn topic is
+  consolidated even within the normal current-development window.
+
+Validation: `yarn compile`, `cargo clippy --all-targets -- -D warnings`,
+`cargo test -q`, `yarn check-agent-interface`,
+`cr docs check-md README.md --entry calcit/test.cirru`, and
+`./scripts/check-docs-md.sh calcit/test.cirru` for the Markdown under `docs/`.

package/editing-history/20260821-1512-type-system-ecosystem-rfcs.md

@@ -0,0 +1,25 @@
+# Type system ecosystem RFCs
+
+- Added a setup-cr proposal that makes `deps.cirru` the normal single source
+  of truth for the Calcit version. Explicit action input remains a fallback;
+  conflicting sources fail instead of silently overriding each other.
+- Defined a native type-quality CI adoption model around `analyze quality`,
+  per-definition baselines, cumulative Q0-Q4 evidence, and explicit backend
+  runtime tests. Project-specific JavaScript report aggregators are rejected.
+- Extended the existing typed JS FFI design with runtime contract evidence,
+  reusable guards/decoders, Node/browser negative fixtures, and auditable
+  unsafe host assertions.
+- Added a long-term static type-system roadmap inspired by Rust and MoonBit:
+  distinguish Unknown from intentional Dynamic, improve exhaustiveness,
+  narrowing and bidirectional local inference, and type framework boundaries
+  before considering more complex trait or effect features.
+- Replaced the obsolete fixed-version GitHub Actions quick start with a
+  `deps.cirru`-driven workflow, and added `setup-cr`/quality-gate metadata so
+  `cr docs search` points users to the relevant CI and upgrade guidance.
+- Removed the RFC index entry for a non-existent project tooling RFC and
+  replaced it with the concrete toolchain contract proposal.
+
+Validation: Markdown structure and Calcit fenced examples are checked with
+`cr docs format-md --check` and `cr docs check-md`; `cr docs search` resolves
+the new setup-cr and quality-gate entry; repository diff is checked for
+whitespace errors.