@calcit/procs 0.12.59 → 0.13.1

package/RFCs/08-04-strict-cirru-edn-decoding-rfc.md

@@ -0,0 +1,342 @@
+# RFC: Cirru EDN 严格类型化反序列化
+
+状态：Implemented / Phase 1 + DataShape 内核（非递归类型）
+日期：2026-08-04
+关联：`07-31-unsafe-coerce-driven-static-type-boundary-plan.md`、`06-01-generic-binding-unification-rfc.md`、`05-31-generic-where-bounds-mfs.md`、Issue #295
+
+## 1. 摘要
+
+新增语言级类型边界：
+
+```cirru
+parse-cirru-edn-as text TypeExpr
+```
+
+它把 Cirru EDN 文本直接解码为满足 `TypeExpr` 的 Calcit 值，并保证：只要调用成功，返回值的完整递归结构、容器元素、struct 字段、enum variant/payload、泛型实参以及名义类型身份都符合目标类型。
+
+该操作不等价于：
+
+```cirru
+unsafe-coerce (parse-cirru-edn text) TypeExpr
+```
+
+后者只建立静态声明，不提供运行时证明；新操作则必须完成实际解析、验证与名义值构造，建立 `validated` 类型证据。
+
+现有 `parse-cirru-edn` 保持兼容，继续作为动态数据接口。严格 API 不允许以 `Dynamic` 作为逃生口；确实需要任意 EDN 时，应显式使用旧动态 API。
+
+## 2. 问题
+
+当前 `parse-cirru-edn` 的返回类型是 `Dynamic`。它的第二个 options map 只根据名称把 record/enum 重新连接到声明对象：
+
+- 不验证 List/Map/Set 内部元素；
+- 不验证 record 字段值的声明类型；
+- 不验证 enum variant 和 payload 类型；
+- 不验证泛型实参与 `:where` 约束；
+- record 字段集合不一致时存在不可恢复的 `unreachable!` 路径；
+- 调用方即使紧接 `assert-type`，当前浅层匹配也不能形成深度证明。
+
+因此 options map 解决的是“名义身份恢复”，不是“类型化反序列化”。把返回值交给 `unsafe-coerce` 只会隐藏边界风险。
+
+## 3. 设计原则
+
+1. **动态与已验证边界分离**：动态解析和严格解码使用不同名字、不同静态语义。
+2. **禁止隐式退化**：严格解码图中不存在 `Dynamic`、未绑定类型变量或未知自定义节点。
+3. **直接构造目标值**：严格解码从 `cirru_edn::Edn` 直接生成目标 Calcit 值，不先生成动态值再做浅检查。
+4. **名义身份精确**：struct/enum 使用编译器解析到的实际声明对象，不能仅凭同名结构冒充。
+5. **Native/JS 同一规则**：两个后端使用同构的解码图和错误路径语义。
+6. **失败可定位**：错误包含目标类型与数据路径，例如 `$.friends[2].age`。
+7. **旧 API 兼容**：本 RFC 不改变 `parse-cirru-edn` 的现有成功结果；迁移由调用方逐处完成。
+
+## 4. 表面语法与静态语义
+
+### 4.1 基本形式
+
+```cirru
+parse-cirru-edn-as raw Person
+
+parse-cirru-edn-as raw $ :: 'List 'Number
+
+parse-cirru-edn-as raw $ :: Box 'String
+```
+
+`TypeExpr` 使用现有类型表达式规则。命名 struct/enum 推荐直接使用声明值（如 `Person`、`Box`）；内建类型与泛型应用继续使用现有 `::` 表达方式。
+
+该形式是 syntax，而不是普通 proc，原因有三点：
+
+- 编译器必须在运行前解析并验证 `TypeExpr`；
+- 返回类型就是 `TypeExpr`，不能退化为 proc 的固定 `Dynamic`；
+- JS codegen 需要把类型解析结果编译为后端无关的解码图。
+
+### 4.2 允许的目标类型
+
+Phase 1 支持：
+
+- `Unit`、`Bool`、`Number`、`String`、`Symbol`、`Tag`、`Buffer`、`CirruQuote`；
+- `Optional<T>`；
+- `List<T>`、`Set<T>`、`Map<K,V>`、`Ref<T>`；
+- 具有完整字段类型的 `defstruct`；
+- 具有完整 variant/payload 类型的 `defenum`；
+- 上述类型的有限组合；
+- 所有泛型实参均已给出的 struct/enum 应用。
+
+Phase 1 明确拒绝：
+
+- `Dynamic`，以及裸 `List`/`Map`/`Set`/`Ref` 所隐含的 Dynamic 参数；
+- 未绑定 `TypeVar`、未解析或未绑定的 `TypeSlot`；
+- 泛型参数缺失、过多或不满足 `:where`；
+- `Fn`、proc、trait、impl、`JsObject`、任意宿主引用；
+- 未知 `Custom` 类型；
+- 没有 enum 声明身份的普通 tuple；
+- `Variadic<T>`（它是函数参数约束，不是数据类型）。
+
+拒绝发生在预处理/编译阶段。动态输入不能迫使编译器生成“遇到不懂的节点就接受”的解码器。
+
+### 4.3 返回类型
+
+静态分析把整个表达式推断为已经解析、完成泛型替换后的 `TypeExpr`，其证据等级为 `validated`。Phase 1 先把类型本身接入现有推断；证据等级的结构化查询等后续静态分析基础设施具备后再暴露。
+
+### 4.4 错误模型
+
+为保持与 `parse-cirru-edn` 一致，Phase 1 在失败时抛出可被 `try` 捕获的错误，而不是额外引入标准库 `Result` 依赖。
+
+错误至少包含：
+
+- 错误类别：文本解析失败、kind 不匹配、名义名称不匹配、字段集合不匹配、variant 不存在、payload arity 不匹配、值类型不匹配；
+- 目标类型；
+- 结构路径；
+- 实际 EDN kind 或名称。
+
+示例：
+
+```text
+parse-cirru-edn-as failed at $.friends[2].age: expected number, got string
+```
+
+## 5. 严格构造规则
+
+### 5.1 标量和容器
+
+- 标量必须匹配对应 EDN variant，不做字符串到数字等隐式转换；
+- `Optional<T>` 只把 EDN `nil` 解释为缺失，否则按 `T` 解码；
+- List/Set/Map 对每个元素或键值递归解码；
+- `Ref<T>` 只接受 EDN `atom`，并对 atom 内部值递归解码；
+- Map key 与 value 都必须满足各自目标类型。
+
+### 5.2 Struct
+
+- 输入必须是 `%{}` record，不能把普通 map 自动提升为 struct；
+- EDN record 名必须和声明名一致；
+- 字段集合必须精确一致：未知字段和缺失字段都是错误；
+- 不以 `nil` 代替缺失字段，不读取默认值；
+- 字段值按泛型替换后的字段类型递归解码；
+- 成功值的 `struct_ref` 必须是目标声明对象，保留其 trait/impl。
+
+### 5.3 Enum
+
+- 输入必须是 `%::` enum tuple，普通 `::` tuple 不自动升级；
+- EDN enum 名必须和声明名一致；
+- variant 必须存在；
+- payload arity 必须精确一致；
+- payload 按泛型替换后的类型逐项递归解码；
+- 成功值的 `sum_type` 必须是目标 enum 声明对象。
+
+### 5.4 泛型和 `:where`
+
+对 `Box<String>`：
+
+1. 检查 `Box` 的泛型参数数量；
+2. 建立 `{T -> String}` 绑定；
+3. 检查 `T` 对应的 `:where` trait 约束；
+4. 把字段/variant 中的 `T` 替换为 `String`；
+5. 对替换后的图递归执行同样的可解码性检查。
+
+泛型函数内部不能依赖运行时反射出 `T`。后续公开 `EdnDecoder<T>` 后，泛型函数必须显式接收 decoder dictionary。
+
+## 6. 共享的闭合数据形状
+
+严格 EDN 解码已经提炼为编译器内部的 `DataShapeGraph`。EDN 执行器只负责“怎样从 EDN 读取节点”；名称解析、泛型替换、`:where` 检查和名义类型绑定都只在 shape 构建阶段执行一次。后续 JSON、FFI、持久化和 diff/patch 必须复用该 shape，不能各自实现一套不完整的类型反射。
+
+### 6.1 当前 ABI
+
+```text
+DataShapeGraph {
+  version: 1
+  root: NodeId
+  fingerprint: MD5(ABI version + complete normalized graph)
+  nodes: [DataShapeNode]
+}
+
+DataShapeNode =
+  Unit | Bool | Number | String | Symbol | Tag | Buffer | CirruQuote
+  Optional(NodeId)
+  List(NodeId)
+  Set(NodeId)
+  Map { key: NodeId, value: NodeId }
+  Ref(NodeId)
+  Struct {
+    nominal_path: Namespace/Definition
+    type_args: [ClosedType]
+    fields: [(FieldTag, NodeId)]
+  }
+  Enum {
+    nominal_path: Namespace/Definition
+    type_args: [ClosedType]
+    variants: [(VariantTag, [NodeId])]
+  }
+```
+
+`fingerprint` 覆盖 ABI 版本、root、所有节点、名义声明路径、完整泛型实参、字段顺序和 variant payload。它不是安全散列或输入签名，而是防止把一个类型的编译产物误用于另一个 schema 的兼容性标识。
+
+构建阶段拒绝 Dynamic、未绑定变量、不完整泛型、失败的 where-bound、未知 custom 类型和递归 slot。每个 child node id 在 graph 完成时校验。Phase 1 暂不接受递归类型；node id 表示使未来增加 cycle-safe 占位节点时不必改写消费者模型。
+
+关键不变量是：
+
+> `DataShape<T>` 构建成功，表示 `T` 是一个可由编译器完整遍历并精确重建名义身份的闭合数据类型。
+
+### 6.2 数据边界如何复用 shape
+
+每一种边界由两部分组成：共享 shape + 格式策略。
+
+| 能力 | 共享部分 | 格式专有部分 |
+| --- | --- | --- |
+| Cirru EDN decode | `DataShape<T>` | EDN kind、record/enum 编码与错误路径 |
+| JSON decode | `DataShape<T>` | tag、map key、enum 的 JSON 表示策略 |
+| FFI/message decode | `DataShape<T>` | 宿主值读取与资源限制 |
+| typed patch | `DataShape<T>` | patch 操作、冲突和集合 diff 策略 |
+
+新边界要么返回经过完整 shape 验证的 `T`，要么明确返回 Dynamic。禁止以浅层 `assert-type` 或只恢复 record 名称的方式把动态值升级成 `T`。
+
+当前不公开可伪造的普通 record 形式 `DataShape<T>`。一等 `EdnDecoder<T>` / `DataShape<T>` 需要先有编译器派生、不可伪造的泛型 dictionary ABI；在此之前 `parse-cirru-edn-as` 继续是公开入口。
+
+### 6.3 typed struct 更新是 patch 的前置能力
+
+typed patch 不能建立在返回宽泛 `Record` 的 `assoc` 上。对于已知 `Struct<A...>`，核心语言必须保证：
+
+1. 字段存在；
+2. 写入值满足泛型替换后的字段类型；
+3. `assoc` / `with` 返回原接收者的精确名义类型和泛型实参；
+4. 编译器可把字段 tag 改写为位置索引，运行时仍保留 tag 作为一致性检查。
+
+当前实现已覆盖以上四点：预处理按替换后的字段类型检查并生成 index/tag，Native indexed runtime 也会重新核对非负整数 index 与 field tag，防止旧 patch 在 schema 漂移后静默写入相邻字段。这一能力应成为所有 typed patch apply 的唯一 struct 写入路径。
+
+## 7. `Patch<T>` 的具体协议
+
+Recollect 当前的 `diff-twig` / `patch-twig` 继续处理开放数据树，其 Dynamic 签名是合理的兼容 API。静态业务状态另行使用不可伪造的 `Patch<T>`：
+
+```text
+Patch<T> {
+  shape_version: 1
+  shape_fingerprint: String
+  root: PatchNode
+}
+
+PatchNode =
+  Keep { node: NodeId }
+  Replace { node: NodeId, value: TypedValue(node) }
+  StructFields { node: NodeId, fields: [(FieldIndex, PatchNode)] }
+  EnumPayload { node: NodeId, variant: VariantIndex, payloads: [(PayloadIndex, PatchNode)] }
+  ListOps { node: NodeId, ops: [TypedListOp] }
+  MapOps { node: NodeId, ops: [TypedMapOp] }
+  SetOps { node: NodeId, ops: [TypedSetOp] }
+  RefValue { node: NodeId, patch: PatchNode }
+```
+
+具体约束：
+
+- 每个 patch node 都声明它对应的 shape node；apply 时必须逐层匹配；
+- `Replace` 和容器 op 的 payload 在创建或反序列化 patch 时按对应子 shape 验证，内部不得出现 Dynamic payload；
+- struct path 使用 field index，apply 同时核对声明中的 field tag，避免 schema 漂移后误写相邻字段；
+- enum variant 变化直接使用 `Replace`；variant 相同时才允许 payload 增量；
+- `Ref<T>` 默认按 opaque/replace 处理，只有显式策略才递归修改可变引用；
+- apply 首先校验 `shape_version` 和 `shape_fingerprint`，成功返回的类型始终为原来的 `T`；
+- 网络或磁盘中的 patch 不是可信内部值，必须通过专用的 strict patch decoder 构造。
+
+应满足：
+
+> `apply(shape<T>, old, diff(shape<T>, old, next, strategy)) = Ok(next)`
+>
+> `apply(shape<T>, old, patch) = Ok(value)` 蕴含 `value: T`，且保持 struct/enum 名义身份。
+
+### 7.1 核心与 Recollect 的职责边界
+
+| Calcit 核心负责 | Recollect 负责 |
+| --- | --- |
+| `DataShape<T>` 派生、ABI 与 fingerprint | diff 启发式与遍历调度 |
+| typed struct/enum 构造和 indexed 更新 | keyed list（如 `:id`）策略 |
+| 不透明 `Patch<T>` 的校验和 apply 原语 | patch 合并、压缩和 memoization |
+| Native/JS/WASM 一致的节点语义 | 开放 Dynamic tree 的兼容 API |
+| patch strict decoder | 面向应用的 strategy 组合 API |
+
+`DiffStrategy<T>` 绑定到 shape node 或静态路径。Recollect 的 `{:key :id}` 在派生 strategy 时应验证目标节点是 list、元素是 struct/map，且 key 字段存在并具有可比较的闭合类型；不能等运行到某条动态数据才发现策略不适用。
+
+首个内部落地切片已实现 `Keep`、`Replace`、`StructFields` 和 `EnumPayload`：patch 创建和 apply 都核对 node id，替换值通过子 shape 验证，apply 核对 ABI version/fingerprint，并保留 base struct/enum 的名义对象。它暂时不暴露语言 API，也不接受普通 Map/tuple 伪造；下一步才是 dictionary/decoder surface 与 Recollect list/map/set strategy 的接入。
+
+Recollect 的现有 Dynamic API 已先完成一项兼容性收紧：`change-op` 统一用名义 enum 构造，`:map-splice` 的 removed payload 修正为 `Set<Dynamic>`。这能在 operation 产生时检查 variant/arity/container kind，但不把 Dynamic payload 冒充为 `Patch<T>`。
+
+## 8. 与旧 API 的关系
+
+| API | 用途 | 静态结果 | 运行时保证 |
+| --- | --- | --- | --- |
+| `parse-cirru-edn text [options]` | 任意 EDN、旧代码兼容 | `Dynamic` | 语法有效；options 仅恢复部分身份 |
+| `unsafe-coerce value T` | 显式信任外部保证 | `T` / trusted | 不验证、不转换 |
+| `assert-type value T` | 现有浅层断言 | 原值 | 仅当前 matcher 覆盖范围 |
+| `parse-cirru-edn-as text T` | 严格类型化反序列化 | `T` / validated | 深度结构与名义身份满足 `T` |
+
+旧 API 不自动弃用，因为 REPL、配置浏览、代码数据和开放 EDN 都有合理的动态使用场景。文档应把它称为动态解析，并优先向业务状态恢复推荐严格 API。
+
+## 9. 实施阶段
+
+### Phase 1：严格闭环（已完成）
+
+- 新增 `parse-cirru-edn-as` syntax 和静态返回类型；
+- 构建无 Dynamic 节点的 `DataShapeGraph`；
+- Native 执行器直接从 `cirru_edn::Edn` 构造类型化值；
+- JS codegen 输出等价 graph，JS runtime 执行同样规则；
+- 支持有限 struct/enum 组合、泛型替换与 where-bound；
+- 增加成功、深层失败、名义名称失败、字段集合失败、variant/arity 失败和编译期拒绝用例；
+- 文档明确旧 options map 的能力边界。
+
+### Phase 2：共享 data shape 内核（内部实现已完成）与一等 decoder dictionary
+
+- 已从 decoder 派生逻辑中提炼编译器内部 `DataShapeGraph`，Native/JS strict EDN 共用；
+- 已让 typed record assoc/with 校验替换后的字段类型并保持精确接收者类型；
+- 引入不可伪造的 `EdnDecoder<T>`；
+- 先让命名类型解析和 schema 展开具备 cycle-safe 能力，再开放递归 struct/enum graph；
+- `edn-decoder T` 编译期派生并 hoist graph；
+- 泛型函数显式接收 `EdnDecoder<T>`；
+- 提供 `decode-cirru-edn` 和 `decode-edn` 的 Result 版本；
+- 允许显式组合 decoder，但不允许从普通 Map/Record 构造。
+
+### Phase 3：typed diff/patch（内部最小 apply 内核已完成）
+
+- 已实现内部 `DataPatch` 的 `Keep`、`Replace`、`StructFields`、`EnumPayload`；
+- 已让 struct 字段和 enum payload patch 绑定到 `DataShapeGraph` node，并校验 index/tag；
+- 已让内部 patch apply 校验 ABI/fingerprint、递归结果类型并保持名义身份；
+- 引入一等、不透明的 `Patch<T>` 与 `DiffStrategy<T>` surface；
+- 增加 list/map/set typed operations 和 strategy；
+- 为 patch 的跨进程传输提供同样严格的 decoder，不暴露 Dynamic payload；
+- 以 Recollect 的 round-trip 和嵌套 record/map fixtures 验证语义，再决定共享执行器的下沉边界。
+
+### Phase 4：受控的格式演进
+
+- 设计显式 custom decoder / migration API；
+- 默认值、旧字段名、版本迁移只能通过 custom 节点引入；
+- custom decoder 的结果仍必须进入最终目标类型的已验证构造路径。
+
+## 10. 兼容性与风险
+
+- 新 syntax 不改变旧代码；
+- 严格 API 有意拒绝不完整类型，不能为了兼容改成 warning 或 Dynamic fallback；
+- 编译期图构建可能增加时间，后续按规范化类型指纹缓存；
+- 后续 recursive graph 必须设置构建中占位节点和执行深度/输入规模保护，避免恶意数据造成栈或资源耗尽；
+- Native/JS 任一端暂不支持的节点应在编译期统一拒绝，不能只让某后端失败。
+
+## 11. 验收标准
+
+1. `parse-cirru-edn-as` 的推断结果为目标闭合类型；
+2. `List<Map<Tag, Person>>` 等嵌套值逐层校验；
+3. struct/enum 成功值携带精确声明身份和 impl；
+4. Dynamic、缺泛型、未绑定变量、函数/trait/JS object 在运行前被拒绝；
+5. Native 与 JS 对相同输入同时成功，或在同一路径以同一错误类别失败；
+6. 旧 `parse-cirru-edn` 行为保持兼容，并移除 record 字段不匹配的 panic 路径；
+7. 文档与集成测试覆盖动态解析、严格解码和 unsafe coercion 三种边界的区别。

package/RFCs/08-05-systematic-nil-reduction-rfc.md

@@ -0,0 +1,174 @@
+# 系统性减少 nil：类型驱动迁移 RFC
+
+状态：Complete（下一版本发布候选；公开 nil 契约已冻结）
+日期：2026-08-05
+
+## 目标
+
+在不掩盖现有运行时行为的前提下，让类型系统逐步阻止业务代码依赖 `nil`：
+
+- 无业务返回值使用 `Unit`（运行时暂仍由 `nil` 承载）；
+- 正常的“可能缺失”最终使用名义类型 `Option<T>`；
+- 可恢复失败使用 `Result<T, E>`；
+- JavaScript `null`/`undefined` 只通过 `JsNullish<T>` 进入类型系统；
+- `Optional<T>` 不再是公开 API 类型，只作为编译器识别旧 schema 与内部自举债务的兼容表示；
+- 参数可以省略是调用约定，不再借用 `Optional<T>` 表示。
+
+这不是立即删除运行时 `nil`。迁移顺序是先让类型契约诚实，再由诊断推动调用方显式处理，最后收紧遗留运行时行为。
+
+## 下一版本稳定性冻结
+
+下一版本是 nil 迁移的最终 breaking window。该版本合并、升级并发布后，以下规则进入兼容性承诺：
+
+- 公开缺失统一返回 `Option<T>`，公开可恢复失败统一返回 `Result<T,E>`，副作用返回 `Unit`；
+- 公开 schema 不得出现 `Optional<T>`。预处理器会发出 `W_LEGACY_OPTIONAL_SCHEMA`，该规则同样约束 `calcit.core` 的公开定义；
+- 名称以 `&` 开头的 raw primitive 属于 semver-private 实现细节，允许在内部使用 nullable 表示，但不得直接挂入公开方法表；
+- 已生成 JS bundle 引用的 npm runtime export 属于 codegen ABI：typed wrapper/raw proc 改名时必须保留兼容 export，并由 runtime identity test 覆盖；类型系统负责阻断重新编译的旧 FFI 源码，但不能替代旧 bundle 的装载兼容性；
+- 新增查询 API 不得先返回 nil、再在后续版本改成 Option。类型和所有后端实现必须在首次发布时一致；
+- `analyze weak-types --only code-nil --intent unresolved,declared-optional` 必须对 core 返回零结果；
+- 以后若要改变这些名义返回类型，只能作为独立的非 nil 设计变更处理，不能再以“清理遗留 nil”为由制造连续 breaking change。
+
+本次最终迁移表：
+
+| 旧契约 | 下一版本契约 |
+| --- | --- |
+| `first` / `last` / `nth` / `get` / `get-in` 返回值或 nil | `Option<T>` |
+| Map/Set `.destruct` 暴露 nullable tuple | `MapDestruct<K,V>` / `SetDestruct<T>` |
+| Record `.nth` 暴露跨后端不稳定字段顺序 | 移除公开方法；字段名 `get -> Option<T>` |
+| `parse-float` 返回 number 或 nil | `Result<Number,String>` |
+| `get-env` 返回 string 或 nil | `Option<String>` |
+| `when-let` 返回 body 或 nil | `Option<R>` |
+| `update-in` updater 接收值或 nil | updater 接收 `Option<T>` |
+| 非穷尽 `case` / `cond` 隐式返回 nil | 明确报错；`cond` 要求最终 `true` 分支 |
+| `dissoc-in` 空路径返回 nil | 空路径保持输入值不变 |
+
+## 已确认的现状
+
+当前实现已经具备迁移所需的主要构件：
+
+- `CalcitTypeAnnotation::Optional(T)` 能表达 `T | nil`；
+- `CalcitTypeAnnotation::JsNullish(T)` 独立表达 JavaScript 宿主空值，不与 Optional/Option 相互匹配；
+- `nil` 推断为 `Unit`，且 `Unit` 可以匹配 `Optional<T>`；
+- `nil?` / `some?` 已支持分支内的 Optional 类型收窄；
+- core 已定义 `Option<T>`、`Result<T, E>` 及基本组合函数；
+- `get` 对 List、Map 和 String 已采用可能缺失的返回推断。
+
+主要障碍不是缺少类型，而是边界契约与历史兼容行为不一致：
+
+1. 内建过程曾用参数类型上的 `Optional<T>` 同时表示“参数可省略”和“传入值可为 nil”；
+2. 部分运行时会返回 nil 的过程仍声明为裸类型或 Dynamic；
+3. `first`、`rest`、`get`、集合转换及无 else 的 `if` 等旧行为，使 nil 可以在未声明的情况下扩散；
+4. core schema、Rust proc 签名、专用类型推断之间存在重复事实来源。
+
+## 语义边界
+
+### Unit
+
+`Unit` 只用于副作用操作或明确没有有意义返回值的表达式，例如写文件、注册 watcher。运行时目前仍由 `nil` 承载 Unit，但源码不应因此显式返回 `nil` 或 `;nil`：空函数体直接声明 `Unit`，有副作用的函数让最后一个 Unit effect 自然成为返回项。只有语法必须提供占位节点时才保留 `;nil`，业务代码不得把它当缺失值容器。
+
+### Optional<T>（遗留内部表示）
+
+`Optional<T>` 只用于识别旧 schema 和尚未完成自举迁移的 core 内部契约。非 core 的公开函数 schema 不再允许声明 Optional；普通缺失必须使用 Option，失败使用 Result，无业务返回使用 Unit。
+
+### JsNullish<T>
+
+JS FFI 是无法立即消除的宿主空值边界。原生属性读取、方法调用、`aget`/`js-get` 与未声明的 `js/...` 调用返回 `JsNullish<JsObject>`：JsNullish 表达 `null`/`undefined`，不透明的 `JsObject` payload 仍要求调用方验证、转换或在可信契约处 `unsafe-coerce`。使用 `js-nullish?`/`js-present?` 收窄；旧 `nil?`/`some?` 会产生专用迁移诊断。
+
+`JsNullish<T>` 不匹配 `Optional<T>`，因此不能传给通用 `optionally` 静默包装。只有显式 `js-nullish->option` 可以建立 `Option<T>`，且该转换不负责验证 opaque payload。
+
+### Option<T>
+
+新设计的查询、解析和集合查找 API 应返回 `Option<T>`。`%some` / `%none` 是普通名义值，不依赖 truthiness，也不会与 Unit 混淆。
+
+### Result<T, E>
+
+格式错误、IO 错误、解码失败等带原因的失败应使用 `Result<T, E>`。只有真正无错误信息价值的缺失才使用 Option。
+
+### 可省略参数
+
+参数可省略属于函数/过程的 arity 元数据。参数声明为 `T` 时，若调用方提供该位置，值必须匹配 `T`；只有参数值类型明确为 `Optional<T>` 时才允许显式传 nil。
+
+## 分阶段实施
+
+### Phase 1：契约诚实化与语义拆分
+
+- 内建过程用独立 arity 元数据表示末尾可省略参数；
+- proc 参数检查不再剥离 `Optional<T>`；
+- 将底层 `&parse-float` 和 `&get-env` proc 的 nullable 返回标成 Optional，作为公开名义 API 之下的兼容边界；
+- 将 `rest` / `butlast` 对空 List 的结果统一为同类型空 List，并同步 Native、JS、WASM；`rest` 与 `empty` 的公开契约改为 `T -> T`，因此确定存在的集合/String 不再被无条件提升为 Optional，而显式 Optional/nil 输入仍保留其可空类型；
+- 公开 core 的 `first`、`last`、`nth`、`get`、`get-in` schema 返回名义 `Option`；内部 `&list:first`、`&list:nth`、`&map:get` 等 raw primitive 保留 nullable 表示并标记为 internal；
+- `analyze weak-types` 将裸 `nil` 与 `;nil` 都纳入审计，仅在结构上可证明的返回位置读取函数契约，并区分 `declared-unit`、`declared-optional` 与 `unresolved`；JSON 对后两类迁移债务发出 `W_NIL_TYPE_DEBT`；
+- `analyze.weak-types` 的机器协议升级到 schema v2，避免旧消费者在 v1 下错误接受新增的封闭 intent/diagnostic 枚举；
+- 修正既有 `optionally` 桥接函数的契约为 `Optional<T> -> Option<T>`，为遗留 nullable 边界提供不丢失类型关系的显式出口；
+- 为上述规则增加单元测试。
+
+Phase 1 的类型契约修正本身不改变相关过程的运行时返回值；`rest` / `butlast` 的空集合修正与后续名义 API 切换则是单独记录的 breaking change。
+
+低层专用推断不能通过批量 `unsafe-coerce` 清理：core 宏在检查列表形状后读取 AST，当前类型系统尚不能携带“非空列表”及 guard clause 终止证据。此类宏改用明确的 `&` raw primitive；公开包装器始终保留 Option 外层，不把内部 nullable 表示扩散成 API。
+
+nil 审计也坚持证据边界：返回的 `do` 只有最后一项继承返回契约，返回的 `if` 只有结果分支继承契约；中间步骤、集合内容和尚未建模的控制流仍标成 `unresolved`。`declared-unit` 不计入迁移债务，`declared-optional` 则继续提示迁移到 Option/Result。
+
+### Phase 2：建立名义安全 API
+
+- 直接将原有 `find`、`find-index`、`index-of` 改为返回 `Option`，让旧调用在结果消费处产生明确的类型迁移提示；
+- 将公开 `parse-float` 改为 `String -> Result<Number,String>`，`:err` 保留原始非法输入；nullable 底层过程改名为内部 `&parse-float`；
+- 将公开 `get-env` 改为 `String -> Option<String>`，删除旧的第二个默认值参数；迁移时使用 `option:unwrap-or`，nullable 底层过程改名为内部 `&get-env`；
+- `optionally` 仅保留为 core/internal 遗留 Optional 到 Option 的桥接，不接受 JsNullish；
+- 反射 API `tuple-enum`、`impl-origin` 返回名义 `Option`，nullable 的 `&tuple:enum`、`&impl:origin` 只保留为内部原语；`record-struct` 则收紧为必然返回 `Struct`；
+- `destruct-list/map/set/str` 从匿名 `:: :some/:none` tuple 升级到参数化的名义 `*Destruct` enum，让 variant 载荷参与类型检查；
+- 泛型实参无法确定时，只把未绑定 payload 降为 Dynamic，保留 `Option<Dynamic>` / `Result<...,Dynamic>` 等外层名义类型，避免整个结果退化成 Dynamic；
+- 对 `some?`/`nil?`、位置式 `get`/`nth` 以及底层 `&compare` 消费名义 enum 的旧 nullable 用法报告 `W_NOMINAL_ENUM_LEGACY_USE`，提示改用 Option 方法、unwrap 或 `tag-match`；
+- core schema 成为公开函数契约，Rust proc 签名负责底层过程契约，并增加一致性审计。
+
+core 自举宏已经迁到明确的 `&` raw primitive，公开 `first`、`last`、`nth`、`get` 不再承担 Optional 债务。JS FFI 独立为 `JsNullish<JsObject>`，不会跟随这些 API 自动变为 Option，也不能通过 `optionally` 擦除边界。
+
+### Phase 3：typed code 严格化（已完成本 RFC 范围）
+
+在启用类型检查的代码中逐项收紧：
+
+- 禁止将 `Optional<T>` 直接传给要求 `T` 的参数；
+- 非穷尽 `case` 运行时报错，`cond` 必须提供最终 `true` 分支；可能缺失的业务值显式返回 Option；
+- 条件表达式要求 Bool，不再依赖 nil truthiness；
+- `first`、`rest`、`get`、`map`、`filter`、`to-list`、`to-map` 等不再接受 nil 作为正常集合；
+- 部分 Record 省略字段必须由字段类型或显式默认值许可。
+
+每条规则先提供稳定诊断码和修复提示，再升级为错误。无类型代码继续走兼容路径，直到单独决定移除窗口。
+
+### Phase 4：收缩运行时 nil（公开边界已完成）
+
+- 公共安全 API 的返回值已切换为 Option/Result/Unit；
+- 删除已无调用方的 nil-tolerant 分支；
+- Optional 仅由迁移工具与 internal raw primitive 识别；公开 schema 由稳定诊断阻断；
+- 审计 JS/WASM 后端，确保名义类型的表示和分支行为一致。
+
+## 类型提示修复策略
+
+迁移应优先给出局部、可机械执行的建议：
+
+- `Optional<T> -> T`：提示先用 `some?`/`nil?` 收窄，或转换为 Option；
+- `JsNullish<T> -> T`：提示使用 `js-present?`/`js-nullish?` 收窄，验证 opaque payload，并只在显式需要时调用 `js-nullish->option`；
+- 缺少 else：提示补 else、改为 `Option<T>`，或明确声明 `Optional<T>` 兼容边界；
+- nil 作为集合：提示在来源处处理缺失，不自动替换成空集合，因为二者业务语义不同；
+- 可省略参数处显式传 nil：提示省略参数，或修改参数值类型为 Optional；
+- 解析返回 Optional：提示改用后续的 Result API，以保留错误信息。
+- 名义 Option 仍用 `some?`/`nil?` 或 tuple 位置读取：提示改用 `option:some?`、`option:none?`、`option:unwrap-or` 或 `tag-match`。
+
+自动修复不得把 nil 无条件替换为空集合、0、空字符串或 false。
+
+## 兼容性与验收
+
+每个阶段必须满足：
+
+1. proc 运行时行为与声明返回类型一致；
+2. 参数 arity 与参数值类型分别测试；
+3. Native、JS、WASM 的可观察结果一致；
+4. 新诊断包含稳定代码、位置和明确修复方向；
+5. examples、core、真实外部项目分别统计新增诊断，不能只依赖单元测试；
+6. 本 RFC 的破坏性变更集中进入下一版本发布说明；该版本以后禁止继续追加 nil 驱动的 breaking change。
+
+## 非目标
+
+- 不把所有 `nil` 机械替换成 `%none`；
+- 不在同一阶段修改全部 core 集合语义；
+- 不用 Dynamic 掩盖无法建模的缺失；
+- 不承诺 Option/Result 与 FFI 的零成本表示，边界转换需要单独设计和测试。

package/RFCs/README.md

@@ -1,6 +1,6 @@
 # RFC 整理索引
 
-更新时间：2026-07-30
+更新时间：2026-08-05
 
 ## 目录原则
 
@@ -39,6 +39,8 @@
 | `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-04-strict-cirru-edn-decoding-rfc.md`            | Implemented   | Phase 1：`parse-cirru-edn-as` 严格类型化反序列化、无 Dynamic 的 `EdnDecoderGraph`、名义身份与 Native/JS 一致性。    |
+| `08-05-systematic-nil-reduction-rfc.md`              | Partial       | 类型驱动减少 nil：先拆分可省略参数与 nullable 值，再迁移至 Option/Result 并逐步收紧 typed code。                  |
 
 ## 已执行的清理
 

package/editing-history/202608050112-nil-reduction-foundation.md

@@ -0,0 +1,33 @@
+# Nil reduction foundation
+
+## 修改概要
+
+- 将内建过程的末尾可省略参数改为独立 arity 元数据，不再把参数值类型写成 `Optional<T>`；
+- proc 参数检查保留 `Optional<T>` 的 nullable 值语义，不再为已提供参数自动剥离 Optional；
+- 修正 `parse-float` 与 `get-env` 的底层返回签名，使其覆盖实际 nil 返回；
+- 增加系统性减少 nil 的分阶段 RFC，明确 Unit、Optional、Option、Result 和可省略参数的边界；
+- 保留内部 List/Map 低层查询的 Dynamic/专用推断兼容点，避免在缺少非空集合证据时用 `unsafe-coerce` 抹掉泛型信息。
+- 扩展 `analyze weak-types` 的 nil 审计：只在可证明的返回位置使用声明契约，区分 `declared-unit`、`declared-optional` 和 `unresolved`，并输出 `W_NIL_TYPE_DEBT`。
+- 修正 `calcit.core/optionally` 的 schema，由错误的 `T -> Optional<T>` 改为实际语义 `Optional<T> -> Option<T>`，并补充 `%some`/`%none` 示例与 schema 回归测试。
+
+## 知识点
+
+- nullable value 与 omitted argument 是正交语义，不能共用 `Optional<T>`；
+- 修正底层查询返回类型会立即暴露 core 宏对非空 List 的隐含前提；在类型系统能表达 guard clause 终止和 NonEmptyList 证据前，批量强制转换不是安全迁移；
+- 高层 `first`、`nth`、`get` schema 已能向 typed code 暴露 Optional，低层 `&list:*` / `&map:*` 兼容点应单独审计和收缩；
+- `parse-float` 的 core schema 已是 Optional，但 Rust proc 签名仍曾声明 Number，说明重复契约需要持续做一致性检查。
+- nil 合理性不能仅由函数返回类型向整个函数体传播；`do` 的中间项仍可能是遗留 sentinel，只有真实返回位置可以安全继承 Unit/Optional 契约。
+- Optional 到 Option 的桥接必须保留泛型关联；将返回值继续标成 Optional 会让 nominal Option 的分支穷尽与方法推断全部失效。
+
+## 验证
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-all`
+- `yarn check-agent-interface`
+- `cr calcit/test.cirru analyze check-examples --ns calcit.core --def optionally`
+- `cr calcit/test.cirru eval "let ((x (optionally (parse-float |1)))) (assert-type x (:: 'Option 'Number)) , x"`
+- `cr ~/.config/calcit/modules/respo.calcit/calcit.cirru analyze check-types --summary-only`
+- `target/debug/cr ~/.config/calcit/modules/respo.calcit/calcit.cirru analyze weak-types --only code-nil --intent unresolved,declared-optional --deps --summary-only --format json`

package/editing-history/202608050943-pr-review-and-test-nil-reduction.md

@@ -0,0 +1,29 @@
+# PR review and test nil reduction
+
+## 修改概要
+
+- 处理 PR #297 的四条有效 review：`optionally` 使用 nominal `%some`/`%none`，schema 测试绑定同一类型变量，单表达式 `do` 识别返回位置，`analyze.weak-types` 协议升级到 v2；
+- 为 `optionally` 增加 enum prototype 示例，避免结构相等掩盖 nominal 身份丢失；
+- 将 `test-enum.main/unwrap-maybe` 从 `Optional<T>` 迁移为 `Option<T>`，测试同步使用 `%some`/`%none`；
+- 将十个空 reload 和五个 Unit callback 的裸 nil 改为显式 `(;nil)`，保留专门验证 nil/Optional 兼容行为的用例；
+- 测试代码合计减少 17 个作为默认返回或缺失 sentinel 的 nil 字面量。
+
+## 知识点
+
+- 普通 `:: :some` / `:: :none` 只构造结构 tuple，不会附着 `Option` enum prototype；值相等不足以验证 nominal 身份；
+- 泛型桥接测试必须验证输入输出共享同一个 TypeVar，否则 `Optional<T> -> Option<U>` 也会误通过；
+- `do` 的第一个 child 是操作符，单表达式返回项位于 index 1，多表达式仍只有最后一项是返回位置；
+- 机器协议中的封闭枚举新增值属于破坏性变化，需要升级 schema version，而不是让 v1 消费者静默遇到未知值；
+- 无业务值返回应显式走 Unit；测试缺失值应优先使用 Option，只有验证兼容边界时保留 raw nil。
+
+## 验证
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-all`
+- `yarn check-agent-interface`
+- `cr calcit/test.cirru analyze check-examples --ns calcit.core --def optionally`
+- `cr calcit/test-enum.cirru`
+- Respo type coverage 与 nil debt JSON 回归

package/editing-history/202608051010-explicit-unit-without-nil.md

@@ -0,0 +1,30 @@
+# Explicit Unit without nil forms
+
+## 修改概要
+
+- 将十个测试 fixture 的空 `reload!` 改为空函数体，并把 schema 从 `Dynamic` 收紧为 `Fn() -> Unit`；
+- 将五个 dummy trait callback 的 `;nil` body 改为空 body，同时把对应 trait method 从无签名 `:fn` 收紧为泛型参数到 `Unit` 返回；
+- 删除 `&init-builtin-impls!` 已由 `Unit` schema 覆盖的显式 `;nil` else，并让 `;nil` 宏自身用空 body 自然产生 Unit；
+- 为 `;nil` 增加一个只验证兼容边界的 Unit example；
+- `analyze weak-types --only code-nil` 现在同时识别裸 `nil` 与 `;nil`，并提示已声明 Unit 的代码删除多余显式 nil form；
+- 测试代码移除 15 个 `;nil`，core 普通实现再移除 2 个显式 nil form；只在专门验证 `;nil` 兼容语义的 example 中保留一次调用。
+
+## 知识点
+
+- Calcit 空 `defn`/`fn` body 会自然返回运行时 Unit；有显式 `Unit` schema 时，不需要用 `nil` 或 `;nil` 重复表达“无返回值”；
+- trait method 可以用 `:: :fn`、泛型 receiver 与 `'Unit` 返回声明 no-value contract，避免 `:fn` 抹掉 callback 返回类型；
+- `;nil` 仍可作为旧宏或必须提供 AST 占位节点的兼容工具，但不能成为绕过 nil 审计的方式；
+- 顶层 eval 的 `(;nil)` 会形成额外一层调用并二次求值；验证宏本身应使用顶层 `;nil`，嵌套参数位置才写 `(;nil)`。
+
+## 验证
+
+- focused weak-types Unit/`;nil` tests
+- modified fixture check-only/runtime tests
+- `calcit.core/;nil` example
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-all`
+- `yarn check-agent-interface`
+- Respo type coverage 与 nil debt 回归