@calcit/procs 0.13.59 → 0.13.61

package/RFCs/08-29-snapshot-symbol-keys-and-tag-match-deprecation-rfc.md

@@ -0,0 +1,39 @@
+# Snapshot Symbol Keys and `tag-match` Deprecation RFC
+
+Status: Implemented / 已实现
+
+## 中文
+
+### 背景
+
+Architecture 文件已经用 Symbol 表示 definition FQN，而 `calcit.cirru` 的 `:files` 与 `:defs` key 仍由 formatter 写成 String。两套持久化表示增加了工具转换成本，也使“标识符”和“普通文本”的语义边界不一致。与此同时，宏 `tag-match` 会在展开后丢失原生 enum 分支结构，不利于穷尽性、payload arity、类型推断及后端优化；原生 `match` 已具备替代条件。
+
+### 决策
+
+1. Snapshot loader 对 namespace/definition key 同时接受 String 与 Symbol。
+2. Snapshot formatter 和 writer 只输出 Symbol key，形成“宽读、窄写”的单向迁移。
+3. String 与 Symbol 归一化后重名时立即报错，不允许 HashMap 静默覆盖。
+4. runtime、format migration 与 detailed snapshot 读取路径共享同一兼容规则。
+5. `tag-match` 标记普通 `:deprecated`；`analyze deprecated` 会报告调用，`analyze quality` 会把调用计入 `deprecatedCalls`。新代码及迁移代码使用原生 `match`。
+
+### 兼容性
+
+旧 Snapshot 无需先手工修改即可读取。首次执行 `calcit calcit.cirru edit format` 后会产生标识符 key 的规范化 diff，应单独审阅并提交。新版本写出的 Symbol key 不保证旧 Calcit formatter 可读，因此项目必须先升级工具链再格式化。
+
+## English
+
+### Context
+
+Architecture files already represent definition FQNs as Symbols, while the `calcit.cirru` formatter still writes `:files` and `:defs` keys as Strings. Maintaining two persistent representations adds conversion work and blurs the semantic boundary between identifiers and text. The `tag-match` macro also hides native enum branch structure after expansion, limiting exhaustiveness, payload-arity, type-inference, and backend optimization passes; native `match` now covers its intended use.
+
+### Decision
+
+1. Snapshot loaders accept both String and Symbol namespace/definition keys.
+2. Snapshot formatters and writers emit only Symbol keys, providing a wide-read/narrow-write migration.
+3. A normalized String/Symbol collision is rejected explicitly instead of being silently overwritten by a HashMap insertion.
+4. Runtime, format-migration, and detailed-snapshot readers share the same compatibility rule.
+5. `tag-match` receives the ordinary `:deprecated` tag. `analyze deprecated` reports calls and `analyze quality` includes them in `deprecatedCalls`. New and migrated code uses native `match`.
+
+### Compatibility
+
+Legacy Snapshots remain readable without manual edits. The first `calcit calcit.cirru edit format` run produces a canonical identifier-key diff that should be reviewed and committed separately. Because older Calcit formatters are not guaranteed to read newly written Symbol keys, projects must upgrade their toolchain before formatting.

package/RFCs/README.md

@@ -1,6 +1,6 @@
 # RFC 整理索引
 
-更新时间：2026-08-26
+更新时间：2026-08-29
 
 ## 目录原则
 
@@ -50,6 +50,7 @@
 | `08-21-static-type-system-evolution-roadmap.md`       | Draft       | 借鉴 Rust/MoonBit 推进 Unknown/Dynamic 分离、穷尽性、局部推断、trait coherence 与框架类型化。 |
 | `08-23-typed-option-query-ergonomics-rfc.md`           | Withdrawn | 生态采用率为零；`get-or` 等六个宏已移除，直接使用查询返回的 `Option` 与 `.unwrap-or`。 |
 | `08-23-option-result-binding-macros-rfc.md`             | Partial | 保留已有 Respo 使用的 `option:let`；移除未采用的 `result:let`，Result 链直接使用 `.and-then`。 |
+| `08-29-snapshot-symbol-keys-and-tag-match-deprecation-rfc.md` | Implemented | Snapshot namespace/definition key 宽读 String/Symbol、窄写 Symbol；`tag-match` 普通废弃并迁移到原生 `match`。 |
 
 ## 已执行的清理
 

package/build.rs

@@ -107,6 +107,26 @@ pub struct Snapshot {
   pub files: HashMap<String, FileInSnapShot>,
 }
 
+fn parse_snapshot_identifier_key(value: &Edn, owner: &str) -> Result<String, String> {
+  match value {
+    Edn::Str(text) | Edn::Symbol(text) if !text.is_empty() => Ok(text.to_string()),
+    Edn::Str(_) | Edn::Symbol(_) => Err(format!("{owner}: snapshot identifier key cannot be empty")),
+    other => Err(format!(
+      "{owner}: snapshot identifier key must be a String or Symbol, got {}",
+      format_edn_preview(other)
+    )),
+  }
+}
+
+fn insert_snapshot_identifier<T>(target: &mut HashMap<String, T>, name: String, value: T, owner: &str) -> Result<(), String> {
+  if target.insert(name.clone(), value).is_some() {
+    return Err(format!(
+      "{owner}: duplicate snapshot identifier `{name}` after normalizing String/Symbol keys"
+    ));
+  }
+  Ok(())
+}
+
 fn parse_snapshot_entry(data: Edn) -> Result<SnapshotEntry, String> {
   let map = data.view_map().map_err(|e| format!("entry must be a map: {e}"))?;
   let ns_def = |key: &str| match map.get_or_nil(key) {
@@ -516,9 +536,10 @@ fn parse_file_in_snapshot(edn: Edn, file_name: &str) -> Result<FileInSnapShot, S
           other => return Err(format!("{file_name}: expected `:defs` map, got {}", format_edn_preview(other))),
         };
         for (def_key, def_value) in &map.0 {
-          let name: String = from_edn(def_key.clone()).map_err(|e| format!("{file_name}: invalid def key: {e}"))?;
+          let name = parse_snapshot_identifier_key(def_key, &format!("{file_name}/:defs"))?;
           let owner = format!("{file_name}/{name}");
-          defs.insert(name, parse_code_entry(def_value.clone(), &owner)?);
+          let entry = parse_code_entry(def_value.clone(), &owner)?;
+          insert_snapshot_identifier(&mut defs, name, entry, &format!("{file_name}/:defs"))?;
         }
       }
       _ => {}
@@ -535,8 +556,9 @@ fn parse_files(edn: Edn) -> Result<HashMap<String, FileInSnapShot>, String> {
     Edn::Map(map) => {
       let mut result = HashMap::with_capacity(map.0.len());
       for (key, value) in map.0 {
-        let name: String = from_edn(key).map_err(|e| format!("invalid file key: {e}"))?;
-        result.insert(name.clone(), parse_file_in_snapshot(value, &name)?);
+        let name = parse_snapshot_identifier_key(&key, "snapshot/:files")?;
+        let file = parse_file_in_snapshot(value, &name)?;
+        insert_snapshot_identifier(&mut result, name, file, "snapshot/:files")?;
       }
       Ok(result)
     }

package/editing-history/202608291043-tag-match-snapshot-symbol-keys.md

@@ -0,0 +1,27 @@
+# `tag-match` deprecation and Snapshot Symbol identifier keys
+
+## 中文概要
+
+- 将 `calcit.core/tag-match` 标记为普通 `:deprecated`，迁移说明指向原生 `match`；废弃调用继续进入 `analyze deprecated` 与 quality 的 `deprecatedCalls`。
+- 将 core 内 18 个 Option/Result、collection destructuring 与 IO helper 的实际调用迁移到 `match`，并同步迁移相关 examples 和 definition-attached tests；core deprecated 分析归零。
+- 为保留的兼容宏补充 validated pattern-list 类型断言，使专门的 legacy runtime test 不产生类型告警。
+- Snapshot runtime、format migration、detailed snapshot 和 build-script reader 对 `:files` namespace key、`:defs` definition key 同时接受旧 String 与新 Symbol。
+- Snapshot writer 只输出 Symbol identifier key；String/Symbol 归一化重名时明确报错，避免 HashMap 静默覆盖。
+- core Snapshot 经新版 writer 完成 Symbol key 规范化；build.rs 同步支持该格式。
+
+## English summary
+
+- Marked `calcit.core/tag-match` with the ordinary `:deprecated` tag and directed migration to native `match`; calls remain part of deprecated analysis and the quality `deprecatedCalls` budget.
+- Migrated 18 real core Option/Result, collection-destructuring, and IO-helper call sites to `match`, including related examples and definition-attached tests; core deprecated analysis now reports zero calls.
+- Added validated pattern-list type assertions inside the retained compatibility macro so its dedicated legacy runtime test remains warning-free.
+- Made runtime, format-migration, detailed-snapshot, and build-script readers accept both legacy String and canonical Symbol namespace/definition keys.
+- Made Snapshot writers emit only Symbol identifier keys and reject normalized String/Symbol collisions instead of silently overwriting entries.
+- Canonicalized the bundled core Snapshot to Symbol keys and updated `build.rs` to consume the format.
+
+## Verification notes
+
+- Rust library tests: 580 passed.
+- Core attached tests: 223 passed.
+- `analyze deprecated --deps`: 0 core calls after migration.
+- Temporary legacy-String Snapshot formatted to Symbol keys and reloaded through `query context`.
+- Full Rust, strict clippy, JS/IR/WASM, and Agent interface checks passed before commit/PR.

package/editing-history/202608291125-purge-events-on-async-cancel.md

@@ -0,0 +1,18 @@
+# Async cancellation must purge accepted Emit events
+
+When a Calcit callback cancels its own native async task, later Emit events may
+already have been detached from the shared queue into the same host drain
+batch. Moving the registry handle to Closing blocks new producer events, but a
+queue-only purge cannot see that detached batch.
+
+The cancellation path now purges events still held by the queue immediately
+after `begin_close`. Drain also treats an Emit observed after the task entered
+Closing as cancellation cleanup: it is discarded without a lifecycle error.
+This is safe because the registry cannot reserve an Emit sequence after
+Closing. Reserved Complete/Fail events remain deliverable for exactly-once
+termination.
+
+当 Calcit callback 在同一轮 drain 中取消 native async task 时，后续 Emit 可能
+已经随 batch 从共享队列取出，普通 queue purge 无法再看到它们。取消流程现在会在
+`begin_close` 后立即清理队列；drain 遇到 Closing task 的 Emit 时将其视为取消清理，
+静默 discard，而 terminal 事件仍利用预留容量完成 exactly-once 收尾。

package/editing-history/202608291143-preserve-terminal-on-cancel-purge.md

@@ -0,0 +1,17 @@
+# Preserve queued terminal events during cancellation purge
+
+Review identified that a task may already have queued Complete/Fail behind an
+earlier Emit when the Emit callback requests cancellation. Purging every event
+would remove that terminal while the registry still remembers its terminal
+claim, leaving the task stuck in Closing.
+
+Cancellation now performs a selective Emit-only purge. Queue metadata removes
+the same event sequences and bytes while preserving any queued terminal and
+its exactly-once claim. Tests cover an Emit and Complete already queued before
+cancel, verify only the Emit is purged, and drain the preserved terminal to a
+finished task.
+
+review 指出取消发生时 Complete/Fail 可能已经排在较早 Emit 后面。全量 purge 会
+删除 terminal，却保留 registry 的 terminal claim，导致 task 永久停在 Closing。
+现在取消只按 sequence 清理 Emit，并同步更新 bytes 与 purged metrics；测试覆盖
+取消前 Emit 与 Complete 已同时入队，确认 terminal 被保留并正常完成。

package/editing-history/202608291202-release-0.13.60.md

@@ -0,0 +1,5 @@
+# Release 0.13.60
+
+- Bumped the Rust crate and npm package versions together from `0.13.59` to `0.13.60`.
+- This release includes canonical snapshot identifier keys and corrected async FFI task cancellation: queued `Emit` events are purged without dropping terminal completion or failure events.
+- The async cancellation change prevents stale callback delivery while preserving deterministic task teardown for native modules.

package/editing-history/202608291249-host-capability-boundary.md

@@ -0,0 +1,6 @@
+# Host capability ownership boundary
+
+- Added the architecture rule that separates Calcit core, pure/typed libraries, host adapters, `calcit_native_ffi`, and macros.
+- Documented the current native/Node/browser/WASM capability matrix and canonical JSON, `FsPath`, clock, and typed FFI capability surfaces.
+- Defined required backend evidence, explicit unavailable behavior, macro expansion permissions, module migration order, and the review checklist for new effects.
+- Linked the new architecture document from the installation hub and native FFI reference.

package/editing-history/202608291811-snapshot-mutation-version-guard.md

@@ -0,0 +1,24 @@
+# Snapshot mutation toolchain guard
+
+## Context
+
+Calcit 0.13.60 writes canonical symbol keys for Snapshot namespaces and definitions. A globally installed newer CLI could therefore rewrite a project whose `deps.cirru` and CI still pin an older reader, leaving the project unreadable to its declared toolchain.
+
+## Change
+
+- Added a shared preflight that reads the `deps.cirru` adjacent to the selected Snapshot.
+- Snapshot-writing `edit`, `tree`, `config`, and cursor operations now reject an exact `:calcit-version` mismatch before loading or writing the target file.
+- Read-only commands, dry-runs, cursor navigation, projects without `deps.cirru`, and legacy manifests without `:calcit-version` remain usable.
+- Invalid non-string or non-semver declarations fail with a manifest-specific diagnostic.
+- The failure explains both safe paths: use the pinned Calcit release, or explicitly upgrade the project with `caps <deps-file> upgrade --all`.
+
+## Verification
+
+- Unit coverage for matching, absent, mismatched, and invalid declarations.
+- Real-project smoke confirmed `config show` remains readable while `edit format` is blocked without changing the Snapshot hash.
+- `cargo fmt --check`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-agent-interface` (17/17)
+- `yarn check-all` (Calcit core 223/223, JS/IR/WASM and performance checks)

package/editing-history/202608291814-caps-manifest-argument-order.md

@@ -0,0 +1,3 @@
+# Preserve `caps` manifest argument order in mutation guidance
+
+The custom `deps.cirru` path is a top-level `caps` positional argument. Guidance must use `caps <deps-file> upgrade --all`; placing the path after `upgrade --all` makes argh parse it as a dependency package name. The mismatch regression test now locks the correct ordering.

package/editing-history/202608291822-quote-mutation-guard-path.md

@@ -0,0 +1,3 @@
+# Quote the manifest path in mutation guidance
+
+The Snapshot toolchain guard now renders the adjacent `deps.cirru` path with the existing shell quoting helper. A regression fixture uses a directory containing whitespace and verifies the suggested `caps '<deps-file>' upgrade --all` command remains a single shell argument. The fixture identity also combines a timestamp with an atomic sequence so parallel tests cannot share a manifest.

package/editing-history/202608291827-release-0.13.61.md

@@ -0,0 +1,3 @@
+# Release 0.13.61
+
+Patch release for the Snapshot mutation toolchain guard from PR #517. Snapshot-writing CLI commands now reject a mismatch with adjacent `deps.cirru :calcit-version` before any write, while read-only and dry-run workflows remain available. Diagnostics preserve custom manifest paths, argument order, and shell quoting.

package/lib/package.json

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

package/package.json

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