@calcit/procs 0.13.57 → 0.13.59

package/RFCs/04-15-wasm-compilation-feasibility.md

@@ -253,6 +253,7 @@ WASM GC proposal（2024 年起 V8/SpiderMonkey 已发布）提供：
 2. 继续补充 `calcit.core` 常见高阶路径。
   - `foldl`、`foldl-shortcut`、`foldr-shortcut`、`sort`、`&call-spread` 仍是大量跳过项的源头。
   - 这部分不是为了追求“理论完备”，而是为了减少真实项目中被迫绕开 core helper 的情况。
+  - 2026-08：带显式 comparator 的 `sort` / `&list:sort` 已实现稳定 WASM 排序；一参数 heterogeneous total-order 仍明确拒绝，等待类型化比较协议。
 
 3. 持续扩大 `test-wasm.cirru` 的下游回归覆盖。
   - 每补一个能力，都应优先加一个最小但能锁定语义边界的 WASM 用例。

package/editing-history/202608280826-wasm-stable-list-sort.md

@@ -0,0 +1,17 @@
+# WASM stable list sort / WASM 稳定列表排序
+
+## 中文
+
+- 用稳定 insertion sort 替换 `sort` 与 `&list:sort` 的静默 identity stub。
+- 排序前复制线性内存 list，保持输入不可变；comparator 复用 static、inline、native proc 与动态函数表调用路径。
+- comparator 结果仅在大于零时移动左值，因此 equal/NaN 保持原顺序。
+- 一参数 heterogeneous total-order 明确报 unsupported，不再生成语义错误的 WASM。
+- 增加升序、降序、重复 key 稳定性、输入不可变、动态 comparator 与 unsupported 路径测试。
+
+## English
+
+- Replace the silent identity stubs for `sort` and `&list:sort` with stable insertion sort.
+- Copy the linear-memory list before sorting to preserve input immutability, reusing static, inline, native-proc, and dynamic function-table comparator paths.
+- Move the left value only when the comparator is greater than zero, preserving order for equal and NaN results.
+- Reject the one-argument heterogeneous total-order form explicitly instead of generating semantically incorrect WASM.
+- Add ascending, descending, duplicate stability, input immutability, dynamic comparator, and unsupported-path tests.

package/editing-history/202608281155-document-shared-native-ffi.md

@@ -0,0 +1,13 @@
+# 记录共享 native FFI crate rollout / Document the shared native FFI crate rollout
+
+## 中文
+
+- 在 FFI bindings 与升级手册中推荐使用已发布的 `calcit_native_ffi`，明确 protocol 文档与模块侧实现的职责边界。
+- 记录首批迁移并发布的五个模块版本。
+- 修正升级手册中的 GitHub 仓库名称，并要求稳定 crate version 而非 git hash。
+
+## English
+
+- Recommend the published `calcit_native_ffi` in the FFI bindings and upgrade guide, clarifying the boundary between normative protocol docs and the maintained module-side implementation.
+- Record the first five migrated and released module versions.
+- Fix repository names in the upgrade guide and require stable crate versions instead of git hashes.

package/editing-history/202608281215-review-ffi-responsibility-wording.md

@@ -0,0 +1,11 @@
+# 修正文档责任边界措辞 / Clarify responsibility-boundary wording
+
+## 中文
+
+- 根据 PR review 将模块职责改为非穷举表述。
+- 明确业务参数与逻辑、thread、connection/task registry、cancel state、server lifecycle 和其他领域状态仍由模块维护。
+
+## English
+
+- Make the module-responsibility wording non-exhaustive in response to PR review.
+- Clarify that modules continue to own domain arguments and behavior, threads, connection/task registries, cancellation state, server lifecycles, and other domain-specific state.

package/editing-history/202608281225-document-second-native-ffi-rollout.md

@@ -0,0 +1,11 @@
+# 记录第二批 native FFI rollout / Document the second native FFI rollout
+
+## 中文
+
+- 记录 JSON、Clipboard、Command 与 Regex 的共享 crate 发布版本。
+- 明确 Regex 的 opaque-resource registry 仍属于模块，仅 buffer-v1 transport adapter 进入共享层。
+
+## English
+
+- Record the shared-crate releases for JSON, Clipboard, Command, and Regex.
+- Clarify that Regex retains its module-owned opaque-resource registry and shares only the buffer-v1 transport adapter.

package/editing-history/202608281430-consume-shared-raw-abi.md

@@ -0,0 +1,13 @@
+# 消费共享 raw ABI / Consume the shared raw ABI
+
+## 中文
+
+- Calcit runtime 直接依赖 `calcit_native_ffi 0.1.2` 的 no-default-features raw contract。
+- 删除 host 内重复的 buffer/async/blocking/resource version、symbol、function pointer、C-layout descriptor 与数值常量定义。
+- 保留类型安全 handle/event enum、event queue、task/resource registry、lease、dylib cache 与 callback lifecycle 在 Calcit host。
+
+## English
+
+- Made the Calcit runtime consume the no-default-features raw contract from `calcit_native_ffi 0.1.2` directly.
+- Removed host-local copies of buffer/async/blocking/resource versions, symbols, function pointers, C-layout descriptors, and numeric constants.
+- Kept typed handle/event enums, the event queue, task/resource registries, leases, the dylib cache, and callback lifecycle in the Calcit host.

package/editing-history/202608281450-release-0.13.58.md

@@ -0,0 +1,13 @@
+# 发布 0.13.58 / Release 0.13.58
+
+## 中文
+
+- 发布 WASM 后端显式 comparator 的稳定 list sort。
+- 记录 native FFI 共享 crate 的完整 rollout，并让 runtime 直接消费 `calcit_native_ffi 0.1.2` raw ABI。
+- 保持 C ABI v1 与现有 native 模块兼容，删除 host 内 184 行重复 raw contract 实现。
+
+## English
+
+- Release stable list sorting with an explicit comparator in the WASM backend.
+- Document the complete shared native-FFI rollout and make the runtime consume the raw ABI from `calcit_native_ffi 0.1.2` directly.
+- Preserve C ABI-v1 compatibility with existing native modules while removing 184 lines of duplicated host raw-contract code.

package/editing-history/202608282333-async-queue-byte-budget.md

@@ -0,0 +1,19 @@
+# Async queue byte budget and terminal reserve
+
+## 中文
+
+- native async queue 现在可同时限制事件数和累计 payload bytes，避免大量合法但体积较大的事件在 1024 个 event slots 内消耗过多内存。
+- CLI runtime 使用 64 MiB 总字节预算，并为 `Complete`/`Fail` 预留 16 个 event slots 和 64 KiB；普通 Stream/Server emit 不能侵占这些预留资源。
+- event admission 成功后才分配 sequence；event/byte budget 失败都返回稳定的 `QUEUE_FULL`，不会误占 terminal 或 sequence。
+- coalescing 在字节压力下也能替换同一 Stream 的旧 emit，并精确维护 queued-byte accounting；drain/purge 同样回收字节账本。
+- `--trace-ffi` 的 enqueue accepted/rejected 事件现在包含当前 queued events/bytes，便于定位 slow host 或 producer pressure。
+- 修复 async protocol 文档仍描述 legacy Rust callback fallback 的过时内容。
+
+## English
+
+- The native async queue can now bound both event count and aggregate payload bytes, preventing a queue of individually valid events from consuming excessive memory.
+- The CLI runtime uses a 64 MiB byte budget and reserves 16 event slots plus 64 KiB for `Complete`/`Fail`; ordinary Stream/Server emits cannot consume those reserves.
+- Event sequences are allocated only after admission. Event-count and byte-budget failures both map to stable `QUEUE_FULL` without claiming a sequence or terminal event.
+- Coalescing can replace an older Stream emit under byte pressure while keeping queued-byte accounting exact; drain and purge release the same accounting.
+- Accepted and rejected `--trace-ffi` enqueue events now include current queued event/byte counters for diagnosing slow hosts and producer pressure.
+- Removed stale async protocol documentation that still described the deleted legacy Rust callback fallback.

package/editing-history/202608290048-async-runtime-shutdown.md

@@ -0,0 +1,17 @@
+# 接入异步 runtime 关闭 / Wire async runtime shutdown
+
+## 中文
+
+- Calcit CLI 统一安装 Ctrl-C handler，信号线程只设置原子状态，`on-control-c` 回调改由 host thread 串行执行。
+- 调用 async registry `begin_shutdown`，拒绝未完成 response，调用模块 cancel hook，并给 terminal event 保留 2 秒 grace period。
+- grace period 结束后先关闭 host queue，再按 module/method/task/kind/age 输出诊断并强制 purge/release，避免迟到 producer 竞态。
+- Watch loop 与兼容性 `async-sleep` 共享可唤醒的 shutdown signal，避免 Ctrl-C 后长时间挂起。
+- 添加 response rejection、cancel invocation、grace timeout 强制清理测试，并使用真实 fswatch C-safe Stream 验证 cancel→Complete→release，无强制清理。
+
+## English
+
+- Install one CLI-owned Ctrl-C handler; the signal thread only updates atomic state, while `on-control-c` callbacks run serially on the host thread.
+- Invoke async-registry `begin_shutdown`, reject open responses, call module cancel hooks, and retain a two-second grace period for terminal events.
+- After the deadline, close the host queue first, then diagnose unfinished tasks by module/method/task/kind/age and force purge/release them without a late-producer race.
+- Let watch loops and compatibility `async-sleep` share a wakeable shutdown signal so Ctrl-C cannot leave the process hanging.
+- Cover response rejection, cancel invocation, and forced cleanup after grace, plus a real fswatch C-safe Stream cancel→Complete→release smoke with no forced cleanup.

package/editing-history/202608290107-avoid-duplicate-shutdown-cancel.md

@@ -0,0 +1,13 @@
+# 避免 shutdown 重复取消 / Avoid duplicate shutdown cancellation
+
+## 中文
+
+- 在 `begin_shutdown` 之前保留 lifecycle snapshot，只向原先处于 `Active` 的 task 调用 cancel hook。
+- 如果 `on-control-c` 或业务逻辑已经把 task 转为 `Closing`，全局 shutdown 只等待 terminal，不会重复调用模块取消。
+- 测试断言已在 Closing 的 task 取消次数保持为零，同时继续受 grace timeout 和强制清理保护。
+
+## English
+
+- Preserve the lifecycle snapshot before `begin_shutdown` and invoke cancel hooks only for tasks that were originally `Active`.
+- If `on-control-c` or application logic already moved a task to `Closing`, global shutdown waits for its terminal acknowledgement without calling module cancellation twice.
+- Assert that an already-closing task receives zero additional cancel calls while remaining protected by the grace timeout and forced cleanup.

package/editing-history/202608290110-handle-shutdown-review.md

@@ -0,0 +1,15 @@
+# 完善关闭中断路径 / Complete shutdown interruption paths
+
+## 中文
+
+- 按 condvar 谓词协议在持有 wake mutex 时记录 shutdown 并通知，消除检查状态与进入等待之间的丢失唤醒窗口。
+- Native evaluator 低频检查 shutdown 请求，覆盖普通求值与尾递归执行；`on-control-c` 回调在 host thread 运行时临时暂停该检查。
+- Watch 在收到文件事件后重新检查关闭状态；reload 与 codegen 在阶段之间检查，且无 timeout 的 codegen 也由可中断的 worker 执行。
+- Once-mode 运行出错或被中断后不再提前跳过 async runtime 清理，而是先完成有界取消与回收，再返回原始错误。
+
+## English
+
+- Record shutdown and notify while holding the condition-variable predicate mutex, closing the lost-wakeup window between checking state and waiting.
+- Poll shutdown cheaply during native evaluation, including tail recursion, while temporarily suppressing interruption for the host-thread `on-control-c` callback.
+- Recheck shutdown after watch events and between reload/codegen phases; timeout-free codegen now also runs behind an interruptible worker boundary.
+- Once-mode failures and interruptions no longer bypass async-runtime cleanup: bounded cancellation and reclamation finish before the original error returns.

package/editing-history/202608290144-async-task-queue-metrics.md

@@ -0,0 +1,19 @@
+# 异步 task 队列指标 / Async task queue metrics
+
+## 中文
+
+- 在 async queue 同一把 mutex 下维护有界的 per-task 固定元数据索引，覆盖 queued events、queued bytes、oldest age、accepted、coalesced、queue-full、dequeued 与 purged。
+- Enqueue、coalescing、drain 与 purge 的新增指标工作只更新目标 task，不扫描全 registry，也不复制业务 payload；coalescing 延续队列原有的有界定位逻辑。
+- `--trace-ffi` 在 enqueue/reject/cancel/release 展示 task-local 指标；shutdown 额外按 module/method 汇总 active/closing tasks 与 backlog。
+- Task release 时删除指标状态；forced cleanup 诊断保留最终 backlog 与累计值。
+- 单元测试覆盖 coalescing、queue-full、drain、purge、并发 producer 与 shutdown 后指标归零。
+- Fibo release 五次中位数由 251.208ms 变为 250.554ms（-0.26%，无可见回退）；真实 fswatch 0.0.9 trace 验证 `Emit → cancel → Complete → release` 且 `forced=0`。
+
+## English
+
+- Maintain a bounded fixed-metadata per-task index under the async queue mutex for queued events, queued bytes, oldest age, accepted, coalesced, queue-full, dequeued, and purged counts.
+- The added metric work for enqueue, coalescing, drain, and purge updates only the affected task without scanning the full registry or copying business payloads; coalescing retains the queue's existing bounded lookup.
+- Extend `--trace-ffi` enqueue/reject/cancel/release records with task-local metrics and aggregate active/closing tasks plus backlog by module/method during shutdown.
+- Remove metric state on task release while retaining the final backlog and cumulative counters in forced-cleanup diagnostics.
+- Cover coalescing, queue-full, drain, purge, concurrent producers, and post-shutdown metric removal in tests.
+- The five-run release fibo median changes from 251.208ms to 250.554ms (-0.26%, no visible regression); a real fswatch 0.0.9 trace verifies `Emit → cancel → Complete → release` with `forced=0`.

package/editing-history/202608290154-ffi-metrics-report.md

@@ -0,0 +1,19 @@
+# Native async FFI 指标报告 / Native async FFI metrics report
+
+## 中文
+
+- 新增 `--ffi-metrics`，在进程退出时向 stderr 输出唯一一条带 `schemaVersion` 的 JSON，不污染业务 stdout。
+- 已完成 task 的 queue 与 lifecycle 计数折叠进有界的 module/method 聚合；当前 task 则与 live queue snapshot 合并，避免释放后丢失累计证据或长期保留 capability。
+- Host 统一记录 response deadline timeout，以及 cancel 请求、成功与失败；模块内部 retry 与远端耗时明确由模块自身上报。
+- JSON 提供 totals 和稳定排序的 module/method rows，覆盖 active/closing/completed task、backlog、oldest age 与所有 queue outcome。
+- 单元测试覆盖 deadline timeout 与 cooperative/forced shutdown 后聚合；真实 fswatch 0.0.9 Ctrl-C 验证 `completedTasks=1`、cancel request/success 与 Complete dequeue 均为 1、`forced=0`，指标只出现在 stderr。
+- 默认关闭报告时不执行 completed archive 或 outcome 锁更新，且复用已有 task control mutex、不增加每 task 分配；release fibo 五次中位数为 246.086ms，对比上一阶段 250.554ms 无可见回退。
+
+## English
+
+- Add `--ffi-metrics`, which emits exactly one schema-versioned JSON record to stderr at process exit without contaminating business stdout.
+- Fold completed-task queue and lifecycle counters into bounded module/method aggregates; merge current tasks with a live queue snapshot so release neither erases cumulative evidence nor retains capabilities indefinitely.
+- Count response deadline timeouts and cancellation requests, successes, and failures in the host, while keeping module-internal retries and remote timings module-owned.
+- Provide totals and deterministically ordered module/method rows for active/closing/completed tasks, backlog, oldest age, and every queue outcome.
+- Cover deadline timeout plus cooperative/forced shutdown aggregation in unit tests; a real fswatch 0.0.9 Ctrl-C run reports `completedTasks=1`, one cancel request/success, one completed dequeue, and `forced=0`, only on stderr.
+- When reporting is disabled, skip completed archives and outcome-lock updates, and reuse the existing task-control mutex without adding a per-task allocation. The five-run release fibo median is 246.086ms versus 250.554ms in the previous stage, with no visible regression.

package/editing-history/202608290227-typed-ffi-capabilities.md

@@ -0,0 +1,17 @@
+# 类型化 FFI capability / Typed FFI capabilities
+
+## 中文
+
+- 在 core 中增加 nominal `FfiTask` 与 `FfiResponse`，把 native async AnyRef 限制在各自 wrapper 的 `Dynamic` raw 字段中。
+- 公开生命周期操作采用方法形式：task 使用 `.cancel` / `.cancel-with`，response 使用 `.resolve` / `.reject`；底层 `&ffi-*` procedure 仅由内部适配函数调用。
+- reason 与 payload 使用方法级泛型 `T`。Calcit trait 禁止方法签名包含 `Dynamic`，因此用户值不会在进入 FFI 编码前丢失静态类型。
+- 两种 capability 使用不同 nominal receiver；错误 receiver 会被 method dispatch 确定性拒绝，错误 raw capability 仍由 native 宿主校验 kind、owner、generation 与 lifecycle。
+- 增加可重放的 architecture scaffold、core 构造测试，以及中英双语协议和使用文档。
+
+## English
+
+- Added nominal core `FfiTask` and `FfiResponse` wrappers, confining native async AnyRef values to each wrapper's `Dynamic` raw field.
+- Exposed lifecycle operations as methods: `.cancel` / `.cancel-with` for tasks and `.resolve` / `.reject` for responses. Internal adapters are the only callers of the raw `&ffi-*` procedures.
+- Kept reason and payload values typed with method-level generic `T`. Calcit traits reject `Dynamic` method signatures, so caller-side types survive until FFI encoding.
+- Kept task and response capabilities as distinct nominal receivers. Method dispatch rejects a wrong receiver deterministically, while the native host still validates raw capability kind, owner, generation, and lifecycle.
+- Added a replayable architecture scaffold, core constructor tests, and bilingual protocol and usage documentation.

package/editing-history/202608290240-release-0.13.59.md

@@ -0,0 +1,13 @@
+# 发布 0.13.59 / Release 0.13.59
+
+## 中文
+
+- 发布 core 类型化 native async FFI capability API。
+- `FfiTask` 提供 `.cancel` / `.cancel-with`，`FfiResponse` 提供 `.resolve` / `.reject`。
+- 下游 native 模块可以从稳定版本开始迁移，不需要引用未发布提交。
+
+## English
+
+- Release the typed native async FFI capability API in core.
+- `FfiTask` exposes `.cancel` / `.cancel-with`, while `FfiResponse` exposes `.resolve` / `.reject`.
+- Downstream native modules can migrate from a stable version instead of referencing an unpublished commit.

package/lib/package.json

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

package/package.json

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