@calcit/procs 0.13.58 → 0.13.59

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.58",
+    "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.58",
+  "version": "0.13.59",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.7.0",