@calcit/procs 0.13.14 → 0.13.16

package/RFCs/08-14-todo-placeholder-rfc.md

@@ -0,0 +1,177 @@
+# RFC: `todo!` 未实现占位表达式与静态提醒
+
+状态：Draft  
+日期：2026-08-14  
+关联：`08-14-architecture-scaffold-rfc.md`、`03-05-function-schema-dual-track-rfc.md`、`07-26-static-semantic-analysis-rfc.md`
+
+## 1. 概要
+
+新增与 Rust `todo!()` 对应的 Calcit 占位表达式：
+
+```cirru
+defn validate-order (order)
+  todo! "|implement order validation"
+```
+
+`todo!` 表示“此路径刻意尚未实现”，同时满足三类契约：
+
+- 类型检查：可出现在任意期望返回类型的位置，不产生返回类型 mismatch；
+- 静态诊断：产生带精确 definition/path 的 `W_TODO`，提醒 Agent 仍有未完成工作；
+- 运行时：一旦执行到该路径，native/JS 明确抛出 TODO error，WASM 执行 `unreachable` trap。
+
+它不是 `raise` 的别名。`raise` 表示程序设计中的普通异常路径，静态分析不应据此推断代码未完成；`todo!` 表示开发状态，必须能被结构化查询和完成门禁识别。
+
+## 2. 表面语法
+
+第一版支持零或一个 String 参数：
+
+```cirru.no-check
+todo!
+todo! "|implement app.order/validate-order"
+```
+
+约束：
+
+- 名称使用 `todo!`；`!` 是 Calcit 命名约定的一部分，不采用 Rust 括号宏语法；
+- message 省略时使用稳定默认文本 `TODO: implementation is pending`；
+- message 必须是静态 String literal，保证 analyzer 无需执行代码即可输出原因；
+- 多参数、Tag、动态拼接或 metadata map 第一版拒绝，避免占位表达式演变成日志 API；
+- scaffold 需要携带 planned calls 时，将它们格式化进静态 message，同时仍以 architecture graph 作为机器可读来源。
+
+## 3. 类型语义
+
+### 3.1 Never/bottom
+
+目标语义中，`todo!` 的表达式类型是内部 `Never`（bottom type），不是 `Unit` 或任意伪造的业务类型：
+
+```cirru
+defn load-user (id)
+  ; schema return: User
+  todo! "|load user"
+```
+
+规则：
+
+- actual `Never` 满足任意 expected type，因此不产生 `W_FN_RETURN_TYPE_MISMATCH`；
+- `if` / `match` 的一个分支为 `Never`、另一分支为 `T` 时，整体推断为 `T`；
+- `Never` 不参与泛型变量绑定，不把 `T` 推断成 `Never`；
+- `Never` 没有运行时 value，也不能构造或存入 collection；
+- 第一阶段只作为 compiler internal annotation；不承诺用户可在 schema 中显式写 `'Never`。
+
+当前基础实现以 compiler-known diverging proc 的 `Dynamic` 返回签名避免伪造的返回类型 mismatch，同时由 `W_TODO` 保留“未完成”信息；它尚未改变 `if`/泛型的类型 join。完整 `Never` 是下一阶段的类型系统工作，届时替换该内部表示，而不改变表面语法或诊断协议。
+
+### 3.2 与控制流的关系
+
+`todo!` 是 diverging expression。preprocessor 在它之后仍可保留源码用于展示，但控制流和类型 join 不要求该表达式返回。第一版不借此实现完整的 unreachable-code warning；这可以在未来与 `raise`、`quit!` 的控制流分析统一处理。
+
+## 4. 静态诊断
+
+每个 `todo!` 产生：
+
+```text
+[W_TODO] TODO remains in `app.order/validate-order`: implement order validation
+  at app.order/validate-order @3
+```
+
+Cirru EDN diagnostic 至少包含：
+
+```cirru
+{}
+  :code :W_TODO
+  :severity :warning
+  :namespace 'app.order
+  :definition 'validate-order
+  :path $ [] 3
+  :message "|implement order validation"
+```
+
+诊断策略：
+
+- `W_TODO` 是 completion warning，不是 type warning；同一位置不得再产生伪造的返回类型 mismatch；
+- scaffold dry-run/apply 把它列入 expected warnings，不把新 stub 当成 apply conflict；
+- `cr --check-only` 遵循当前严格 warning 策略：可创建 scaffold，但仍有 reachable TODO 时检查返回非零，Agent 不能宣称功能完成；
+- `cr analyze check-types` 扫描所选 Snapshot definition，将 TODO 数量和 diagnostics 纳入 human/Cirru EDN 报告，即使节点暂时不从 entry 可达；
+- 后续若引入 warning severity/allow-list，`W_TODO` 的默认 completion gate 仍应为 deny，显式探索性运行才允许降级；
+- Cirru EDN stdout 保持单个 value；JSON 只作为现有工具兼容投影，human warning 与普通命令提示走 stderr。
+
+参数契约也由 compiler-known proc 统一执行：`todo!` 只接受零个参数，或一个
+静态 String literal；非 literal 参数和多余参数在 preprocessing 阶段分别报告
+Type/Arity 错误并阻止 codegen。native、JavaScript、WASM backend 仍保留同样的
+校验作为防御性边界，不把非法调用静默降级为 unconditional trap。
+
+## 5. 运行时与 codegen
+
+即使静态门禁通常会先发现 TODO，各后端仍必须定义一致的防御行为：
+
+| 后端 | 行为 |
+|------|------|
+| native | 返回 `CalcitErrKind::Effect`，message 以 `TODO:` 为前缀并附 call stack |
+| JavaScript | 生成 `throw new Error("TODO: ...")` |
+| WASM | 在可选 host log 后执行 `unreachable`；第一版至少保证 trap，不返回伪值 |
+| IR | 保留明确的 todo/diverge 节点，不能降为 `nil` |
+
+`try` 是否能捕获 native/JS TODO 第一版沿用普通 runtime error 机制；静态 `W_TODO` 不因外层存在 `try` 而消失，因为捕获异常不代表实现已经完成。
+
+## 6. 实现形态
+
+推荐将 `todo!` 作为 compiler-known builtin/syntax，而不是 calcit-core 普通函数：
+
+- parser/name resolution 能稳定识别，不受局部同名 binding 影响；
+- type inference 可直接返回 internal `Never`；
+- preprocessor 能在表达式位置产生精确 `W_TODO`；
+- JS/WASM codegen 可直接生成 diverging operation；IR 的显式 todo/diverge 节点留在后续实现；
+- runtime 不需要用普通 `raise` 猜测某段字符串是否以 TODO 开头。
+
+当前实现采用 `CalcitProc::Todo`：preprocessor 对它生成精确 `W_TODO`，Dynamic signature 仅作为完整 `Never` 前的临时内部兼容表示，不能把 warning 当作可忽略的普通动态边界。
+
+## 7. 与 scaffold 的关系
+
+architecture scaffold 默认生成：
+
+```cirru
+defn validate-order (order)
+  todo! "|implement app.order/validate-order; planned calls: app.order/order-total"
+```
+
+- doc/schema/params 正常写入 `CodeEntry`；
+- `:scaffold` tag 与 `W_TODO` 分工：tag 表示 definition 来源，warning 表示代码中仍存在未实现路径；
+- 完成实现时必须移除对应 `todo!`；是否同时自动移除 `:scaffold` tag 由 scaffold completion check 决定；
+- planned edges 仍来自 architecture graph，不把 message 当成可解析协议；
+- 实际 call graph 在实现前可以没有 planned calls，drift report 应把这种缺失标记为 `pending`，而不是伪造不可执行调用。
+
+## 8. 分阶段实现
+
+### Phase A：基础可用版本（已实现）
+
+- 注册 `todo!`；
+- native runtime TODO effect；
+- 精确 `W_TODO` preprocessing diagnostic；
+- function schema return context 测试；
+- 完整 internal Never/bottom、branch/generic 规则留给后续控制流分析。
+
+### Phase B：分析与后端
+
+- `analyze check-types` 全 Snapshot TODO 扫描及 Cirru EDN machine result；
+- JS/WASM codegen 已实现；IR 的显式 todo/diverge 节点仍待实现；
+- `--check-only`、eval、test 和 codegen warning 行为测试；
+- Agent 文档与 error-handling 文档。
+
+### Phase C：scaffold 接入
+
+- scaffold 默认 `--stub todo`；
+- generated/expected warning 分类；
+- TODO 清零和 `:scaffold` tag 完成检查；
+- architecture drift 的 pending edge 表达。
+
+## 9. 验收
+
+- `todo!` 可作为 `'Number`、`'String`、Struct、Enum、generic 和 `Unit` 函数的返回表达式，不产生类型 mismatch；
+- `if condition (todo! "|left") 1` 推断为 Number；
+- 每处 TODO 都产生一个带稳定 `W_TODO`、FQN、path 和 message 的 diagnostic；
+- `analyze check-types` 能发现当前 entry 不可达 definition 内的 TODO；
+- scaffold apply 可成功创建 TODO stub，但完成门禁不会在 `W_TODO` 尚存时通过；
+- native、JS、WASM 执行到 TODO 时均中止，不返回 `nil` 或默认值；
+- `raise "|TODO..."` 不产生 `W_TODO`，普通异常语义保持不变；
+- shadowing 或同名用户 definition 不会被误判为 compiler TODO；
+- Cirru EDN stdout 保持单个 value，兼容 JSON renderer 不改变该纯净度契约；
+- 全部核心、CLI、JS 和 WASM 回归通过。

package/RFCs/README.md

@@ -1,6 +1,6 @@
 # RFC 整理索引
 
-更新时间：2026-08-08
+更新时间：2026-08-14
 
 ## 目录原则
 
@@ -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-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 后续实现。 |
 | `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。                  |
 | `08-08-cross-backend-host-ffi-contracts-rfc.md`      | Draft         | 统一 JS/native/WASM/WASI 的逻辑 FFI 契约与诊断，ABI transport 保持 backend-specific；首个完整 shape consumer 为 JS/DOM。 |

package/editing-history/20260814-1412-architecture-scaffold-rfc-and-cursor-envelope.md

@@ -0,0 +1,46 @@
+# 功能架构脚手架 RFC 与 cursor envelope 兼容性
+
+## 背景
+
+单 definition 的 `cr edit def` 无法直接承载一个功能的调用结构、接口约束、已有节点复用和批量生成计划。未来多个 Agent 拆分实现时，还需要在不承诺同 Snapshot 并发写安全的前提下，确保 cursor sidecar 不会丢弃其他 cursor user 的位置数据。
+
+## 本次结论
+
+- 新增 `RFCs/08-14-architecture-scaffold-rfc.md`，建议以 `cr edit scaffold` 接收 Cirru EDN desired-state overlay；canonical model 是 Symbol FQN 到 declaration 的平面 map 加 typed anonymous-enum edge set（如 `:: :call from to`），tree 只作为展示或未来输入语法糖。
+- architecture declaration 包含 mode、kind、doc、当前 canonical schema、函数参数和可选 code/examples；已有 definition 默认复用，具体 schema/kind 冲突拒绝整次 apply。旧示例中的 quoted `:: 'Fn` 已修正为 unquoted `:: :fn`，只有 code AST 使用 quote。
+- 已有 definition 不会从 scaffold graph 中消失：planner 同时展示 existing/planned doc、schema、kind 和字段级 diff；apply 不覆盖现有内容，差异通过 info/warning/conflict diagnostics 报告。
+- 函数 `:params` 属于程序内部元数据，architecture Cirru EDN 使用 Symbol（如 `'order`），parser 不把 String/Tag 隐式转换成参数名。
+- scaffold stub 不再用普通 `raise`：新增 `08-14-todo-placeholder-rfc.md`，设计 compiler-known `todo!`、internal Never、`W_TODO` 和各后端的 diverging 行为；scaffold apply 可创建 stub，但 TODO 完成门禁仍失败。
+- scaffold 与 TODO 的规范机器结果改用 Cirru EDN，保留 Symbol/Tag/Set/Quote/schema 的数据身份；JSON 只作为既有 Agent、`jq` 和 LSP/MCP 工具的兼容 renderer。
+- 多 Agent 第一版采用“并行产出 definition 实现、parent/coordinator 串行写回 Snapshot”；CLI 只输出带 target/write-set/schema/doc/planned edges 的 work item，不启动 Agent，也不把 call graph 当成硬任务依赖。
+- reconciliation 区分 `create`、`reuse-pending`、`reuse-complete` 和 `external`；带 scaffold/TODO 的已有节点会在重复 dry-run 时继续产生稳定 work item，保证中断后可恢复。
+- definition-level semantic patch、`ensure-import` 和 SCC/batch 建议留到流程走通后；第一版继续复用 Snapshot revision、现有 edit/transaction 与 staged atomic write。
+- 第一版不暴露只有单一有效值的 `--stub`/`--existing` 策略开关，直接固定为 compatible reuse、hard conflict reject 和 TODO stub。
+- cursor 身份仍为 `--cursor-user` > `CALCIT_CURSOR_USER` > `default`，但 architecture 不再把 work item 绑定到 cursor user。未来多 user 推荐 `.calcit/cursors/<user>.cirru`，source mutation 只立即迁移当前 user，其他 user 下次访问时 lazy revalidate。当前新建 v4 sidecar 的默认 cursor key 先从 `main` 改为 `default`。
+- scaffold 只生成普通 `CodeEntry` stub，不增加运行时架构元数据；后续实现和 drift 检查继续复用现有 call graph、query、tree 和 cursor。
+- cursor v4 文件本来已有 `:active` 与 `:cursors` map，但 Rust 内存模型只保留 active state，任何保存都会把 map 收缩为固定 `:main`。
+- `CursorDocument` 现在保存实际 `active_name` 和其他 cursor state，序列化时合并写回，因此可无损 round-trip named cursors；CLI 行为仍只作用于 active entry。
+- architecture 文件实现期间可约定放在 `docs/architectures/<feature>.cirru` 并用 normalized content hash 形成 plan-id；派生的 status/work items/diagnostics 不回写 plan。`.calcit/` 只承载本地临时 cursor 状态。
+- 本轮没有实现 cursor user 选择、per-user 文件、semantic patch、lease、心跳或并发锁；这些都不阻塞 architecture → scaffold → work items → 串行整合的第一版闭环。
+
+## 验证
+
+- `cargo fmt --all -- --check`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-agent-interface`（12/12）
+- `yarn check-all`
+- `cargo test --bin cr cli_handlers::cursor::tests`（19/19，包含 `default` key 与 named cursor round-trip）
+- 用 `cr cirru parse-edn` 验证 RFC 中 architecture、machine result 与 work item 示例；带空格 doc 使用双引号保护 pipe string。
+- architecture result、TODO diagnostic、通用 machine envelope 与 Definition Descriptor 的 EDN 示例均通过 `cr cirru parse-edn`。
+
+新增/扩展的 cursor round-trip 测试覆盖非默认 active 名称和非 active cursor 条目的保存与恢复。
+
+## Scaffold 与 `todo!` 基础实现进度
+
+- 新增 `cr edit scaffold`；接受平面 architecture Cirru EDN，输出 human、canonical EDN 或 JSON compatibility projection。
+- parser 强制 FQN/params 使用 Symbol，edge 使用匿名 enum（`:: :call from to` / `:: :type from to`），拒绝误用异构 list 的 edge。
+- planner 验证 roots/edge endpoint、schema 与 namespace，reconcile 现有 definition，并输出 create/reuse-pending/reuse-complete/external、预览 operation 和带 plan/base revision/write-set 的 work item。
+- `--dry-run` 保持只读；apply 在 staged Snapshot 中一次创建全部缺失 `:ensure` definition，function 生成 `todo!` stub，写入 doc/schema/`:scaffold`，复核原 revision 后 atomic rename，绝不覆盖已有 definition。apply 成功后触发已有 cursor 后置校验。
+- 新增 compiler-known `todo!` proc：native effect 中断，preprocessor 产生 `W_TODO`，JS/WASM codegen 均显式中断。完整 Never/branch/generic inference、definition-level patch 和 external dependency/core lookup 仍待后续实现。

package/editing-history/20260814-1640-architecture-scaffold-review-fixes.md

@@ -0,0 +1,21 @@
+# 2026-08-14 16:40 — architecture scaffold review fixes
+
+## Summary
+
+- Processed PR #351 review comments for scaffold reconciliation, metadata preservation, machine-result revisions/diffs, work-item identity, and writer concurrency.
+- Made explicit function code, tags, examples, and data code survive scaffold apply; generated `:scaffold` only for TODO function stubs.
+- Added empty-root validation, external target compatibility validation, per-definition diffs, proposed/applied revisions, and post-scaffold work-item revisions.
+- Added a destination writer lock around staged snapshot replacement and strengthened the named-cursor round-trip fixture with distinct states.
+- Enforced one `todo!` argument contract across preprocessing, JavaScript, WASM, and native boundaries; diagnostics now identify the containing definition and invalid messages use the argument location.
+- Expanded the machine-protocol RFC with canonical JSON tagged projections and stdio framing/negotiation fixtures, and aligned the cursor default example with `:default`.
+- Added a concrete nested EDN/JSON typed-value fixture and equivalent EDN/JSON handshake fixture requirements.
+
+## Validation
+
+- `cargo fmt --all`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-agent-interface`
+- `yarn check-all`
+- `cr docs check-md` for all modified RFC and static-analysis documents

package/editing-history/20260814-1700-fix-bare-empty-map-js-codegen.md

@@ -0,0 +1,10 @@
+# Bare empty-map JS codegen
+
+- A bare Cirru `{}` survives preprocessing as `CalcitProc::NativeMap`, rather
+  than as an already-created map value.
+- JS code generation must invoke that runtime constructor when it is used as a
+  value. Emitting the escaped proc name alone produced `$clt._$M_`, an alias
+  that the runtime does not export.
+- Keep a focused codegen test for the emitted `$clt._$n__$M_()` call. This
+  protects empty map values in typed struct constructors and ordinary calls
+  such as `merge {} other`.

package/editing-history/20260814-1710-map-codegen-callee-context.md

@@ -0,0 +1,9 @@
+# Empty-map codegen needs callee context
+
+- In JS codegen a bare `CalcitProc::NativeMap` must produce an empty map by
+  invoking the runtime constructor.
+- The same proc at the head of a list is the constructor callee and must not be
+  pre-invoked. Otherwise generated code becomes `map()(...entries)`.
+- Keep separate regression assertions for the bare value and an entry-bearing
+  map literal, and run the emitted-JS Node suite because unit output alone
+  cannot catch a callee/value context mix-up.

package/editing-history/20260814-1720-option-membership-method-guidance.md

@@ -0,0 +1,11 @@
+# Typed Option membership and method-style guidance
+
+- The nominal-enum legacy-absence warning now permits `includes?` / `contains?`
+  when the candidate and the checked collection element are statically the same
+  nominal enum. This keeps `Set<Option<T>>` membership type-safe without
+  treating an `Option` as a nullable payload.
+- Added a regression test covering `includes?` over `Set<Option<Number>>`.
+- Updated Option/Result user-facing documentation to prefer receiver methods
+  such as `.and-then`, `.or-else`, `.map`, and `.unwrap-or`; direct
+  `option:*` / `result:*` helpers remain implementation-level compatibility
+  details rather than the recommended public style.

package/editing-history/20260814-1746-pr-352-review-fix.md

@@ -0,0 +1,8 @@
+# PR 352 review boundary correction
+
+- `List.contains?` tests index presence rather than membership of list values.
+- Restrict the nominal-enum membership warning exemption accordingly: only
+  `includes?` uses list elements, while `contains?` applies to Set elements or
+  Map keys.
+- Added a regression assertion that `contains?` with `List<Option<T>>` still
+  reports the migration warning.

package/editing-history/20260814-1858-map-wrapped-data-definitions.md

@@ -0,0 +1,11 @@
+# Map-wrapped data-definition macro forms
+
+- `defstruct Name $ {}` and `defenum Name $ {}` deliver one map-headed AST
+  wrapper through their variadic macro parameters. Normalize that wrapper into
+  the contained field or variant forms before detecting generics and where
+  bounds.
+- Compare the macro AST head with quoted `'{}`; evaluating `{}` would instead
+  create a runtime map and fails to recognize the syntax marker.
+- Added definition-attached end-to-end fixtures for typed Struct field access
+  and Enum construction/tag matching, so both wrapper forms remain covered by
+  the native test suites.

package/editing-history/20260814-1910-assert-type-struct-narrowing.md

@@ -0,0 +1,6 @@
+# 2026-08-14 assert-type Struct 收窄
+
+- `assert-type` 的限定名（例如 `'app.schema/Store`）在非泛型上下文中必须保留为名义 `TypeRef`，不能误作 type variable；这样后续必填 Struct 字段访问才能解析声明。
+- 断言包裹任意表达式时，类型推断应把声明类型交给外层 `let` binding；局部变量的断言仍由预处理阶段直接收窄。
+- `defstruct` / `defenum` 的 `$ {} ...` map-headed 输入已经由宏归一化，静态类型定义解析也必须在泛型和 `:where` 解析前采用相同的归一化。
+- 回归覆盖包括两种断言收窄路径、map-headed Struct/Enum 静态解析，以及完整 Struct/Enum Snapshot 运行。

package/editing-history/20260814-1937-assert-type-direct-definitions.md

@@ -0,0 +1,5 @@
+# 2026-08-14 assert-type 直接类型定义
+
+- `assert-type` 的第二参数是类型语境；未加引号的 symbol 现在会解析为可见的 Struct/Enum 定义，例如 `assert-type source Store`。
+- 单引号继续用于 TypeVar（`'T`）和显式名义 TypeRef，不把泛型变量当作运行时定义求值。
+- 两条 Struct 收窄回归测试改为直接定义写法，覆盖语句断言及 `let` 右侧断言。

package/editing-history/20260814-1945-applied-qualified-type-references.md

@@ -0,0 +1,5 @@
+# 2026-08-14 限定名类型应用
+
+- 未限定泛型语境中，带 `/` 的 TypeRef 仍是名义类型，不应在 `::` 类型应用时退化为普通值。
+- `(:: 'app.schema/Box 'String)` 现在保留 `app.schema/Box` 及其类型参数；保留现有 TypeVar 行为。
+- 添加针对无 scope 限定名类型应用的回归测试，覆盖 `assert-type` 使用的同一类型解析路径。

package/editing-history/20260815-0043-pr-352-assert-type-nominal-guard.md

@@ -0,0 +1,12 @@
+# PR 352 assert-type direct resolution guard
+
+- `assert-type` direct definition resolution now verifies the referenced def
+  resolves to a concrete StructDef/EnumDef before treating it as a resolved type.
+- Visible function or value names are kept as-is instead of being passed to
+  `parse_type_annotation_form` as resolved runtime values, which could silently
+  change the asserted type.
+- Added `code_resolves_to_nominal_type_def` in `type_annotation.rs` reusing the
+  existing `resolve_type_def_from_code` peeling logic.
+- Extended the membership regression block with Map<Option<T>, V> key
+  membership via `contains?`, Map<K, Option<T>> value membership via `includes?`,
+  reversed-direction negatives, and specialized Map membership procs.

package/history/202608131607-runtime-map-decoder.md

@@ -0,0 +1,13 @@
+# Runtime map decoder for typed boundary data
+
+## Change summary
+
+- Added `decode-map-as value TypeExpr`, a compile-time-derived decoder for an already-evaluated Calcit Map.
+- The decoder constructs nominal Struct values recursively, rejects unknown keys and missing required fields, and reports nested failure paths.
+- Struct fields declared as `Option<T>` accept raw `T`, preserve an already-wrapped `%some`/`%none`, and become `%none` when the source field is absent.
+- `Dynamic` is allowed only as an explicit runtime-boundary leaf for this decoder; the existing text-based `parse-cirru-edn-as` remains a closed-data decoder and continues to reject it.
+- Native and JavaScript backends share the graph ABI and tests. WASM continues to reject both typed EDN decoder syntaxes explicitly.
+
+## Knowledge point
+
+Runtime Maps are not Cirru EDN: they do not carry nominal Struct identity and commonly represent optional data by omitted keys. A typed boundary decoder must therefore perform map-to-Struct construction, enforce required fields, and lift omitted or raw optional values into nominal `Option` variants. Reusing the closed EDN decoder without these rules silently permits invalid Structs or forces callers back to ad-hoc dynamic map readers.

package/history/202608131625-core-decode-map-as-metadata.md

@@ -0,0 +1,12 @@
+# Document `decode-map-as` in calcit-core
+
+## Change summary
+
+- Added the `decode-map-as` runtime syntax to the core snapshot metadata with builtin/internal/meta/syntax tags and a typed boundary schema.
+- Added reusable `RuntimeMapMeta` and `RuntimeMapResponse` Struct fixtures for core examples and tests.
+- Added a passing example plus definition-attached unit tests covering recursive Struct decoding through an Option field, omitted `Option` fields becoming `%none`, pre-wrapped `%some`, and explicit Dynamic payload preservation.
+- Documented the native/JavaScript support boundary and kept WASM behavior explicit.
+
+## Knowledge point
+
+Compiler syntax and core snapshot metadata are separate surfaces. Adding a Rust/JS builtin is incomplete until `calcit-core.cirru` exposes its documentation, examples, schema, and tests; otherwise `cr docs`, `cr test`, and downstream agents cannot discover or verify the feature.

package/history/202608131650-release-0.13.15.md

@@ -0,0 +1,10 @@
+# Release Calcit 0.13.15
+
+## Change summary
+
+- Released the merged `decode-map-as` runtime decoder and its core snapshot metadata, examples, and tests.
+- Kept Cargo and npm package versions synchronized at `0.13.15` for the direct-main release workflow.
+
+## Knowledge point
+
+Version-only release changes are allowed directly on `main`; the functional implementation was merged and validated before this release commit. The release tag is created from the synchronized `main` commit so Cargo and npm publish the same version.

package/lib/calcit.procs.d.mts

@@ -247,7 +247,7 @@ export declare let parse_cirru: (code: string) => CalcitCirruQuote;
 export declare let parse_cirru_list: (code: string) => CalcitList;
 export declare let parse_cirru_edn: (code: string, options: CalcitValue) => CalcitValue;
 type DataShapeNode = {
-    kind: "unit" | "bool" | "number" | "string" | "symbol" | "tag" | "buffer" | "cirru-quote";
+    kind: "unit" | "bool" | "number" | "string" | "symbol" | "tag" | "buffer" | "cirru-quote" | "dynamic";
 } | {
     kind: "optional" | "list" | "set" | "ref";
     inner: number;
@@ -255,6 +255,10 @@ type DataShapeNode = {
     kind: "map";
     key: number;
     value: number;
+} | {
+    kind: "map-option";
+    nominal: CalcitEnumDef;
+    inner: number;
 } | {
     kind: "struct";
     nominal: CalcitStructDef;
@@ -274,6 +278,7 @@ type DataShapeGraph = {
     nodes: DataShapeNode[];
 };
 export declare let parse_cirru_edn_as: (code: string, graph: DataShapeGraph) => CalcitValue;
+export declare let decode_map_as: (value: CalcitValue, graph: DataShapeGraph) => CalcitValue;
 export declare let json_parse: (code: CalcitValue) => CalcitValue;
 export declare let json_stringify: (value: CalcitValue) => string;
 export declare let json_pretty: (value: CalcitValue) => string;

package/lib/calcit.procs.mjs

@@ -1746,6 +1746,139 @@ export let parse_cirru_edn_as = (code, graph) => {
     }
     return decode_typed_edn_node(graph, graph.root, input, "$", 0);
 };
+const map_decode_error = (path, message) => {
+    throw new Error(`decode-map-as failed at ${path}: ${message}`);
+};
+const decode_runtime_map_node = (graph, nodeId, input, path, depth) => {
+    if (depth > 1024)
+        map_decode_error(path, "decode nesting exceeds 1024");
+    const node = graph.nodes[nodeId];
+    if (node == null)
+        map_decode_error(path, `invalid data shape node #${nodeId}`);
+    switch (node.kind) {
+        case "dynamic":
+            return input;
+        case "map-option": {
+            if (input instanceof CalcitEnumValue &&
+                (input.enumPrototype === node.nominal || input.enumPrototype?.name() === node.nominal.name())) {
+                const tag = input.tag;
+                if (!(tag instanceof CalcitTag))
+                    map_decode_error(path, "Option variant is not a tag");
+                const tag_name = tag.value;
+                if (tag_name === "none" && input.extra.length === 0)
+                    return input;
+                if (tag_name === "some" && input.extra.length === 1) {
+                    return new CalcitEnumValue(tag, [decode_runtime_map_node(graph, node.inner, input.extra[0], path, depth + 1)], node.nominal);
+                }
+                return map_decode_error(path, "invalid Option value");
+            }
+            return new CalcitEnumValue(newTag("some"), [decode_runtime_map_node(graph, node.inner, input, path, depth + 1)], node.nominal);
+        }
+        case "struct": {
+            if (!(input instanceof CalcitMap || input instanceof CalcitSliceMap)) {
+                return map_decode_error(path, `expected map for struct :${node.nominal.name.value}, got ${typed_edn_kind(input)}`);
+            }
+            const entries = new Map();
+            input.pairs().forEach(([key, value]) => {
+                const name = key instanceof CalcitTag ? key.value : typeof key === "string" ? key : null;
+                if (name == null)
+                    map_decode_error(path, "struct map keys must be tags or strings");
+                if (!node.fields.some(([field]) => field === name)) {
+                    map_decode_error(path, `struct :${node.nominal.name.value} has unknown field :${name}`);
+                }
+                if (entries.has(name))
+                    map_decode_error(path, `struct :${node.nominal.name.value} has duplicate field :${name}`);
+                entries.set(name, value);
+            });
+            const decoded = new Map();
+            node.fields.forEach(([field, child]) => {
+                if (entries.has(field)) {
+                    decoded.set(field, decode_runtime_map_node(graph, child, entries.get(field), `${path}.${field}`, depth + 1));
+                }
+                else {
+                    const fieldNode = graph.nodes[child];
+                    if (fieldNode?.kind === "map-option") {
+                        decoded.set(field, new CalcitEnumValue(newTag("none"), [], fieldNode.nominal));
+                    }
+                    else {
+                        map_decode_error(path, `struct :${node.nominal.name.value} is missing required field :${field}`);
+                    }
+                }
+            });
+            const values = node.nominal.fields.map((field) => decoded.get(field.value));
+            return new CalcitStructValue(node.nominal.name, node.nominal.fields, values, node.nominal);
+        }
+        case "list": {
+            if (!(input instanceof CalcitList || input instanceof CalcitSliceList)) {
+                return map_decode_error(path, `expected list, got ${typed_edn_kind(input)}`);
+            }
+            return new CalcitSliceList(Array.from(input.items()).map((value, idx) => decode_runtime_map_node(graph, node.inner, value, `${path}[${idx}]`, depth + 1)));
+        }
+        case "set": {
+            if (!(input instanceof CalcitSet || input instanceof TypedEdnSetView)) {
+                return map_decode_error(path, `expected set, got ${typed_edn_kind(input)}`);
+            }
+            const values = [];
+            const source = input instanceof TypedEdnSetView ? input.items : input.values();
+            source.forEach((value) => {
+                const decoded = decode_runtime_map_node(graph, node.inner, value, `${path}.item`, depth + 1);
+                if (values.some((item) => _$n__$e_(item, decoded)))
+                    map_decode_error(path, "duplicate decoded set value");
+                values.push(decoded);
+            });
+            return new CalcitSet(values);
+        }
+        case "map": {
+            if (!(input instanceof CalcitMap || input instanceof CalcitSliceMap)) {
+                return map_decode_error(path, `expected map, got ${typed_edn_kind(input)}`);
+            }
+            const entries = [];
+            input.pairs().forEach(([key, value]) => {
+                const decodedKey = decode_runtime_map_node(graph, node.key, key, `${path}.key`, depth + 1);
+                if (entries.some(([existing]) => _$n__$e_(existing, decodedKey)))
+                    map_decode_error(path, "duplicate decoded map key");
+                entries.push([decodedKey, decode_runtime_map_node(graph, node.value, value, `${path}.value`, depth + 1)]);
+            });
+            return new CalcitSliceMap(entries.flat());
+        }
+        case "optional":
+            return input == null ? null : decode_runtime_map_node(graph, node.inner, input, path, depth + 1);
+        case "ref":
+            if (!(input instanceof CalcitRef))
+                return map_decode_error(path, `expected atom, got ${typed_edn_kind(input)}`);
+            return atom(decode_runtime_map_node(graph, node.inner, input.value, `${path}.value`, depth + 1));
+        case "enum": {
+            if (!(input instanceof CalcitEnumValue) || input.enumPrototype == null) {
+                return map_decode_error(path, `expected enum :${node.nominal.name()}, got ${typed_edn_kind(input)}`);
+            }
+            const actualEnumName = enum_prototype_name(input.enumPrototype);
+            if (actualEnumName !== node.nominal.name()) {
+                return map_decode_error(path, `expected enum :${node.nominal.name()}, got enum :${actualEnumName}`);
+            }
+            if (!(input.tag instanceof CalcitTag))
+                return map_decode_error(path, `enum :${node.nominal.name()} variant must be a tag`);
+            const inputTag = input.tag;
+            const variant = node.variants.find((candidate) => candidate.tag === inputTag.value);
+            if (variant == null)
+                return map_decode_error(path, `enum :${node.nominal.name()} has no variant :${inputTag.value}`);
+            if (variant.payload.length !== input.extra.length) {
+                return map_decode_error(path, `enum :${node.nominal.name()} variant :${variant.tag} expects ${variant.payload.length} payload(s), got ${input.extra.length}`);
+            }
+            const values = variant.payload.map((payloadNode, idx) => decode_runtime_map_node(graph, payloadNode, input.extra[idx], `${path}.payload[${idx}]`, depth + 1));
+            return new CalcitEnumValue(newTag(variant.tag), values, node.nominal);
+        }
+        default:
+            return decode_typed_edn_node(graph, nodeId, input, path, depth);
+    }
+};
+export let decode_map_as = (value, graph) => {
+    if (graph.version !== 1)
+        throw new Error(`decode-map-as expected data shape ABI version 1, got ${graph.version}`);
+    if (typeof graph.fingerprint !== "string" || graph.fingerprint.length === 0) {
+        throw new Error("decode-map-as expected a non-empty data shape fingerprint");
+    }
+    return decode_runtime_map_node(graph, graph.root, value, "$", 0);
+};
 const json_to_calcit = (value) => {
     if (value == null)
         return null;

package/lib/package.json

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

package/notes/202608132206-repo-sync.md

@@ -0,0 +1,3 @@
+# Repository sync inventory
+
+Recorded the organization repository inventory in `notes/repos.md`. This pass fetches each repository's latest `origin/main`, switches to an open PR head when one exists, and excludes projects whose declared `deps.cirru` Calcit version is `0.13.15`.