cross-tab-worker-databus 0.20.89 → 0.20.91

package/docs/zh/benchmarks.md

@@ -2,19 +2,19 @@
 
 # 浏览器基准趋势
 
-> 数据截至 2026-09-12，基于 14 份归档的 `bench-results/browser-*.json` 报告（运行 `pnpm bench:browser` 追加一份；用 `node scripts/bench-trend.mjs` 重新生成本文档）。
+> 数据截至 2026-09-16，基于 24 份归档的 `bench-results/browser-*.json` 报告（运行 `pnpm bench:browser` 追加一份；用 `node scripts/bench-trend.mjs` 重新生成本文档）。
 
 发布门禁的对比基线是最近两份报告之间的 `pnpm bench:compare --fail-above-pct 50`（50% 上限用于吸收共享 runner 的噪声）。本文记录长期趋势：数值为逐指标延迟，越低越好；历史最优为本机观察到的最健康一次运行。
 
 <!-- BENCH-TREND:BEGIN (machine-generated table) -->
 | 指标 | 上次 (ms) | 本次 (ms) | Δ | 历史最优 (ms) |
 |---|---|---|---|---|
-| publish per-message (ms, lower is better) — dedicated | 61.1276 | 58.888 | -2.24 | 40.8227 |
-| publish per-message (ms, lower is better) — shared | 38.5784 | 45.0451 | +6.47 | 33.8206 |
-| wildcard dispatch ×1000 (ms, lower is better) | 6.5 | 7.5 | +1.00 | 0.1 |
-| publishBatch ×1000 (ms, lower is better) | 4.5 | 5.1 | +0.60 | 0.4 |
-| dedup ×1000 (ms, lower is better) | 13.4 | 14.5 | +1.10 | 0 |
-| trace + publish ×1000 (ms, lower is better) | 5.3 | 5.2 | -0.10 | 4.8 |
+| publish per-message (ms, lower is better) — dedicated | 42.335 | 39.5999 | -2.74 | 35.3543 |
+| publish per-message (ms, lower is better) — shared | 35.806 | 34.3455 | -1.46 | 33.6784 |
+| wildcard dispatch ×1000 (ms, lower is better) | 7.2 | 6.8 | -0.40 | 0.1 |
+| publishBatch ×1000 (ms, lower is better) | 4.9 | 4.9 | +0.00 | 0.4 |
+| dedup ×1000 (ms, lower is better) | 21.5 | 16.1 | -5.40 | 0 |
+| trace + publish ×1000 (ms, lower is better) | 5.3 | 4.5 | -0.80 | 4.5 |
 | first-packet cold dispatch (ms, lower is better) | 0.1 | 0 | -0.10 | 0 |
 <!-- BENCH-TREND:END -->
 

package/docs/zh/capabilities.md

@@ -28,7 +28,7 @@
 | 性能 | 协调元数据批量写入 + 退避重试 | ✅ 已实现 | 心跳、路由和 subscriber 写入合并后在微任务中 flush；失败时指数退避；`pagehide` / `stop()` 同步 flush |
 | 性能 | 可选 ArrayBuffer Transferable 传输 | ✅ 已实现 | 开启 `transferable: true` 后，二进制 publish/receive 跳过 structured clone 复制；对象消息 API 不变 |
 | 性能 | 可选 `DataBusTransport.publishBatch` 单帧突发发布 | ✅ 已实现 | 内置 WebSocket transport 将多条消息合并为一帧（`publishBatch` op，demo server 已支持）；无批量能力的 transport 回退逐条 `publish` |
-| 消息语义 | exactly-once 投递 | 未实现 | 正常交接会避免重叠，但异常恢复和 transport/服务端行为仍不提供 exactly-once 保证 |
+| 消息语义 | 端到端 at-least-once 或 exactly-once 投递 | 未实现 | 每条被接受的 transport publication 只会扇出一次，每个匹配的本地 handler 至多分发一次；但 transport/服务端仍可能重复或丢失，断连/挂起期间跨 Tab 事件也可能丢失，按实例有界的可选 `messageId` 去重仍不足以提供端到端 at-least-once 或 exactly-once 保证 |
 | 消息语义 | 可插拔的 publication 去重 | ✅ 已实现 | 按 `DataBusMessage.messageId` 做可选有界入站抑制；默认关闭，ID 仍由调用方/服务端控制 |
 | 认证 | Worker 内异步凭证刷新桥接 | ✅ 已实现 | `createCentrifugeDataBus` 的可选 `credentialProvider`（`getToken` / `getChannelToken`）。Worker 配置保持结构化可克隆；Worker 通过 TOKEN_REQUEST / TOKEN_RESPONSE 交换向主线程请求每个新凭证，由 provider 从应用上下文提供 |
 | 负载策略 | 按消息速率、字节数或调度滞后自适应加权 | ✅ 已实现 | 可选的 `loadWeighting`（`messageRateWeight`、`byteRateWeight`、`scheduleLagWeight`）：Workers 按窗口采样自身 fan-out 流量与心跳调度超时并随记录发布；新 route 的 owner 选择在 Topic 数之上加入归一化速率与滞后比率。默认（未设置）保持纯按 Topic 数；已有 route 保持 sticky |

package/docs/zh/release-checklist.md

@@ -30,7 +30,7 @@
 
 ## 打 tag 的发布工作流
 
-推送版本 tag 会触发 `Release` GitHub Action：先跑 `pnpm check` 与 `pnpm lint`（tag 可能指向从未通过 CI lint 步骤的提交），再跑 `verify:compat` 与 `verify:pack`，从 `CHANGELOG` 对应章节生成 GitHub release，配置了 `NPM_TOKEN` 时自动发布到 npm，然后运行与手动执行相同预算的**阻塞式**消费者验证（`PUBLISHED_VERIFY_ATTEMPTS=24`、`PUBLISHED_VERIFY_DELAY_MS=5000`）。已发布包若无法被干净消费者导入，工作流即失败——任何 `verify:published` 失败都应视为发布失败，修复后重新发布该 tag。未配置 token 时跳过发布步骤，但验证仍会针对 npm 上已有的版本（例如手动发布的）通过。
+推送版本 tag 会触发 `Release` GitHub Action：先跑 `pnpm check` 与 `pnpm lint`（tag 可能指向从未通过 CI lint 步骤的提交），再跑 `verify:compat` 与 `verify:pack`，从 `CHANGELOG` 对应章节生成 GitHub release，配置了 `NPM_TOKEN` 时自动发布到 npm，然后运行与手动执行相同预算的**阻塞式**消费者验证（`PUBLISHED_VERIFY_ATTEMPTS=48`、`PUBLISHED_VERIFY_DELAY_MS=7500`，即 6 分钟上限）。已发布包若无法被干净消费者导入，工作流即失败——任何 `verify:published` 失败都应视为发布失败，修复后重新发布该 tag。未配置 token 时跳过发布步骤，但验证仍会针对 npm 上已有的版本（例如手动发布的）通过。
 
 ## 发布（手动场景）
 
@@ -42,4 +42,4 @@
 2. 在干净消费者中安装已发布版本或 tarball，并导入主入口及所有公开子路径。
 3. 将结果记录到发布说明。在公开 API 和协议弃用策略明确冻结前，不进入 `1.0.0`。
 
-打 tag 的发布工作流已自动执行上述消费者验证；仅在需要离线复验时才手动运行 `PUBLISHED_VERSION=<version> pnpm verify:published`。只有遇到异常慢的镜像才需要调整 `PUBLISHED_VERIFY_ATTEMPTS` 和 `PUBLISHED_VERIFY_DELAY_MS`。
+打 tag 的发布工作流已自动执行上述消费者验证；仅在需要离线复验时才手动运行 `PUBLISHED_VERSION=<version> pnpm verify:published`。工作流默认的 6 分钟上限足以吸收 npm CDN 的正常传播延迟（0.20.89 tag 首次运行在发布成功后排空了旧的 2 分钟预算）；只有遇到异常慢的镜像才需要继续调大 `PUBLISHED_VERIFY_ATTEMPTS` 和 `PUBLISHED_VERIFY_DELAY_MS`。

package/docs/zh/roadmap.md

@@ -1,6 +1,23 @@
 # 路线图
 
-0.20.89 已发布。项目会先持续完成生命周期/就绪与适配器 parity 审计，再进入 1.0.0 稳定性冻结。
+0.20.91 已发布。项目会先持续完成可靠性发布，再进入 1.0.0 稳定性冻结。
+
+## 0.20.91 已完成范围
+
+可靠性开发线继续补强错误路径覆盖并维护发布门禁。IndexedDB replay 清理现在覆盖 `clear()`、`clearTopic()`、`clearBefore()` 的事务级错误，包括连接失效后的恢复，以及浏览器未提供 transaction error 对象时的领域级 fallback 拒绝信息。WebSocket transport 也会在连接失活后 best-effort 关闭 socket，避免自动恢复遗留死连接；已发布包验证的正常路径经审计确认没有固定等待或多余 registry 往返。Centrifuge token bridge provider 现在绑定到创建它的 client lifecycle，已被替换的 client 无法把迟到凭证请求送入新会话。旧 client 的 subscription 回调与 publish rejection 也已有回归约束，不能修改或上报到替代会话。
+DataBus 生命周期审计现在还固定了 failed-reopen 的 stop gate 复用、被取代 initial open 的迟到 rejection 隔离、已退休 transport 迟到的 message/status/error 回调 generation 隔离，以及就绪/恢复契约（`stop()` 后迟到的 `pageshow` 不得重启后台工作、自动恢复再次失败必须通过 `ready()` 暴露、被取消的排队启动不得满足替代重启、排队重启在可用前被挂起必须让 `ready()` reject、旧 recovery timer 不得重开 transport）。本轮审计还发现并修复了一处真实定时器泄漏：`WorkerClusterRuntime.pause()` 在无 channel 时不再排定延迟 `channel.close()`。mutation check 已确认移除对应守卫时每条回归都会失败。本阶段还覆盖 failed-open 后 stop gate 复用、pagehide stop rejection 恢复、replay handler 分发隔离，以及 in-flight recovery reopen 复用；重开守卫已有 mutation 覆盖。
+
+排队 transport 操作审计还固定了：在 initial open 尚未完成时排队的 `subscribe()`，其 rejection 必须恰好通过 `onError` 上报一次且不得成为 unhandled rejection；start gate 放行前不得触碰仍在 opening 的 transport。
+DataBus 生命周期审计还固定了 initial `transport.start()` 被 `stop()` 取代后、teardown 等待期间才 reject 的 rejection ownership：原 `start()` 调用方看到自己的失败，`stop()` 仍成功，transport 恰好关闭一次，旧失败不会进入新 lifecycle 的 error ledger。
+跨 Tab `EVENT` 边界现在会拒绝不是对象、或缺少字符串 `topic` 的 publication payload，因此一条畸形的同源帧不会再从 BroadcastChannel 监听器抛出并破坏后续投递。未知事件类型保持前向兼容；旧版 payload 会继承帧级 `originTabId`，payload 自带归属优先，两项行为均有回归固定。
+
+## 0.20.90 已完成范围
+
+本开发线修复 0.20.89 tag 首发暴露的发布管线问题，并统一文档中的投递语义。
+
+- 发布门禁传播预算：阻塞式已发布包消费者验证从 24 × 5 s（2 分钟）提升为 48 × 7.5 s（6 分钟）。0.20.89 的 tag 首发发布成功之后仍在该门禁失败，因为 `npm pack` 在旧预算内始终返回 `ETARGET`；真正缺失的包仍会耗尽预算而失败。
+- 投递语义：API、架构与能力文档现在一致说明有界的本地 fan-out 保证，并明确 SDK 不提供端到端的 at-least-once 或 exactly-once 投递；中文 API 参考已补充按 bus 可选启用的 `messageId` 去重窗口。
+- 发布性能证据：基准趋势文档已基于 23 份归档报告刷新；最近两次运行对比未超过 50% 上限，两种 Worker 模式的单消息发布延迟均有改善。
 
 ## 0.20.89 已完成范围
 
@@ -506,7 +523,7 @@
 ## 0.13.0 候选
 
 1. 冻结公共导出面与 transport 无关的 publication 信封。
-2. 精确记录 at-least-once 投递与去重保证。
+2. ~~精确记录 at-least-once 投递与去重保证。~~ 已交付：architecture/API/capability 文档现在明确区分「每条已接受 transport publication 的本地至多一次扇出」与端到端投递，记录 transport/服务端的丢失与重复投递，并说明有界、可选 `messageId` 去重的边界，不再宣称 at-least-once 或 exactly-once。
 3. 增加长时浏览器浸泡覆盖：replay 留存、重连、BFCache 与 owner 迁移。
 4. 为 1.0 前的协议别名发布迁移指南与弃用策略。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cross-tab-worker-databus",
-  "version": "0.20.89",
+  "version": "0.20.91",
   "description": "Framework-agnostic cross-tab data bus with Dedicated/Shared Worker clustering and Centrifuge support.",
   "type": "module",
   "license": "MIT",