refactor(danmuku): [PKG-DANMUKU-04] own scheduler and worker request lifecycle

2026-10-18 02:21:20 -08:00 · 2026-09-13 19:19:25 +08:00
1 parent 0b2efb07f1
commit 12332df221
@@ -0,0 +1,84 @@
+# PKG-DANMUKU-04 时钟、队列与轨道调度
+
+弹幕调度现在只有一个待执行RAF或异步准备帧。新增`src/scheduler.js`负责运行归属、
+取消、失败和恢复，`src/queue.js`负责状态池与候选顺序，`src/worker-client.js`负责
+请求关联和Worker收尾。`danmuku.js`保留公共行为出口；原`worker.js`轨道算法逐字未改。
+本步仍是JS职责拆分，完整TS和最新npm根声明/准确`/runtime`归06。
+
+## 行为与兼容边界
+
+- 原生play/playing可以重复进入start，仍保留旧start事件；内部只能有一条运行链。
+  队列先ready后wait，保留当前媒体时间前后0.1秒窗口、状态池顺序和原轨道几何。
+- 暂停、reset、替换输入成功提交、hide、seeking、destroy以及更换beforeVisible
+  使旧准备工作失效。取消与用户Promise竞速，新工作不必等待旧回调结束。
+  每次await及用户回调后检查归属；回收前检查节点身份，避免旧续体回收新节点。
+- hide、seeking和回调更新保留已显示/暂停节点；seek不额外发reset。Date.now寿命
+  排除暂停时间；同步倍率仍只在新弹幕分配时取值，不顺便改写现有弹幕剩余寿命。
+- beforeVisible拒绝沿现有error出口发原错一次，本轮跳过该项并继续其他项；false
+  仍可下一帧重试。显式start/reset或其他失效动作允许仍符合时间条件的失败项重试。
+  错误监听器自身抛错有局部观察，不产生脱离调用链的未处理RAF拒绝。
+- Worker共享回复监听在post前安装，ID在请求及Worker替换之间递增，避免同毫秒串线。
+  反序、同步、重复、未知和迟到回复不会完成其他请求。取消的内部请求解析为
+  `{ id, result: undefined }`；故障以原错拒绝待处理请求，独立尝试解绑及terminate。
+- Worker故障停止内部调度但不伪造公共stop。后续start/reset可重建；重复失败等待
+  下次显式恢复。错误监听器可能同步destroy/stop/reset/hide或嵌套start，因此恢复
+  后再次检查生命周期、generation和启动序号，过期start不能继续或发迟到start事件。
+- 门面方法、getter、同步/异步返回及内部实例身份保持。配置回调保持当前option为this。
+  合法的NaN时间保持旧currentTime+0.5；零保持03明确修正后的0，正无穷保持原值，
+  负无穷仍钳位0，不扩大原验证器对null等输入的接受范围。
+
+## 发现的问题先修复，再保留证据
+
+最初18项调度测试为6通过12失败；03实际main在两核心的8个Chromium场景为4通过4失败，
+具体包括六条弹幕产生七个请求、同ID及空visible快照、节点复用时留下额外隐藏节点。
+这个03快照本身未重叠，02另有真实重叠记录；没有把不同运行的现象拼成同一次失败。
+
+第一轮候选48项原生矩阵通过后，只读代理发现恢复错误监听器销毁播放器仍继续start。
+补齐destroy/stop/reset/hide/嵌套start五个回归，保存的修复前真实main在32项中27绿5红，
+加入恢复所有权检查后全部转绿。随后复审发现03的`time !== undefined`在修正零时
+误改合法NaN：历史源码/main/legacy均沿旧默认时间，候选24项23绿1红。保留零的显式
+判断并恢复NaN默认路径，增加历史对照和真实浏览器可见性断言；03旧报告保持原样。
+
+这些修复作为本步变更记录，新增已解决风险INPUT-02；没有把中间版本的通过当作最终
+验收。父代理负责复审、构建、浏览器和整合，子代理分别承担调度实现、确定性测试及
+独立风险复核，同一文件分工不重叠，Git由父代理统一提交。
+
+## 最终验证
+
+- 源码、正式main、正式legacy各104项联合通过。每组中83项随候选实现变化，18项
+  直接验证内部Worker客户端/原轨道源码，3项固定历史数值对照。不能把后21项重复
+  宣称为不同产物的额外覆盖。组成：输入24、解析26、调度33、Worker客户端21。
+- 确定性时钟覆盖三小时媒体范围、180批共720条、15次120秒暂停及暂停中seek，
+  执行真实Worker算法，检查每条一次请求、发射顺序、唯一状态池及4节点全程复用。
+  这是采样生命周期的模拟时钟测试，不是实际三小时播放或帧率/内存基准。
+- 三种实现各66项原生浏览器通过，共198项：实际已发布核心5.4.0及候选5.4.1，
+  Chromium/Firefox/Windows WebKit。包括三模式、严格轨道几何、播放/暂停/跳转/倍率、
+  节点复用、四种pending取消、恢复重入、NaN、实际设置/发送/mount和双实例。
+- main和legacy额外各30次密集场景重复，共60次，无跳过、失败或重试后通过。
+  每次六条固定弹幕都断言几何不交叠、顺序、六个唯一请求、visible快照长度0至5、
+  回复关联及六节点；复用场景另断言同一可见节点且额外节点数组为空。
+- 普通场景要求零页面错误、零Worker错误；恢复场景显式派发受控ErrorEvent并让
+  createWorker抛错，仅允许精确已知故障。实际视频/DOM/Blob Worker继续使用原生实现，
+  但不能把注入故障描述成真实CSP或平台Worker构造失败。Windows WebKit不是Safari设备。
+- 仓库正常build生成三格式及docs/compiled，逐一核对字节；修改源码/测试/脚本入口lint
+  通过。04未改生产TS或公开声明，引用03全仓366生产TS和消费者检查，未声称04新跑TS。
+
+构建曾在浏览器运行期间遇Windows UNKNOWN复制错误；停止并行构建后正常串行重建成功，
+核对main/legacy与当时已测试文件哈希一致。NaN修复后再次完整构建并运行上述最终矩阵。
+故障日志、串行重试、字节一致性证明及最终结果均保留。新增所有权逻辑使产物变大，
+机器证据记录相对03的原始/gzip字节，不能声称本步缩包或性能改善。
+
+证据及输入指纹见[机器报告](../baselines/danmuku-scheduler-validation.json)。原始截图和
+附件归档独立目录，报告记录原results路径到归档路径的映射，不手改原Playwright报告。
+未新增依赖或修改Yarn锁；`test:unit`和`test:danmuku`加入调度/Worker客户端测试，新增
+原生spec沿既有浏览器CI发现。中间48/60项矩阵保存为过程证据，最终引用numeric-final。
+
+## 风险关闭与下一步
+
+ASYNC-01由03输入/解析及04可见性/Worker归属共同满足关闭标准；TRACK-01关闭范围仅为
+已复现的重复运行链和请求串线，以及对应严格几何/节点重复回归。它们不代表任意负载、
+任意轨道算法或包级资源稳定性已经验收。CLEANUP-01保持开放：Setting外部DOM、发送
+续体和锁定计时器仍需05处理；heatmap零采样同样未修。05继续DOM渲染/设置/热力图，
+06完整TS与声明，07真实长负载。完整npm安装、发布前多轮复盘仍待各自任务。
+
+本任务完成后独立本地commit，无推送、标签或npm发布。
@@ -4,7 +4,7 @@

 基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 228 项，范围 22 个包及工作区/示例。

-状态：todo 71 / doing 15 / blocked 0 / done 142 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 70 / doing 15 / blocked 0 / done 143 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。

@@ -312,8 +312,8 @@
 | PKG-DANMUKU-01 | artplayer-plugin-danmuku<br>核对弹幕全部公开契约 | BASE-05 | emit/load/config/hide/show/reset/mount、option/isHide/isStop/icons 与事件清单 | 源码、声明、发布包、Bilibili 输入和设置入口对照 | H | done |
 | PKG-DANMUKU-02 | artplayer-plugin-danmuku<br>建立弹幕算法与浏览器基线 | PKG-DANMUKU-01, ENG-05, ENG-08 | 密集/稀疏弹幕、过滤/异步输入、seek/倍率/重载测试 | 轨道选择、发射顺序、事件、内存和可视结果可重跑 | H | done |
 | PKG-DANMUKU-03 | artplayer-plugin-danmuku<br>整理加载、解析与配置 | PKG-DANMUKU-02, CORE-08 | bilibili/input/parser/config 的分层与取消 | 旧格式、回调、过滤、追加/替换语义保持 | M | done |
-| PKG-DANMUKU-04 | artplayer-plugin-danmuku<br>整理时钟、队列与轨道调度 | PKG-DANMUKU-03, CORE-10 | danmuku 调度器和确定性时钟测试 | seek/暂停/倍率/长时间运行无顺序和碰撞回归 | H | doing |
-| PKG-DANMUKU-05 | artplayer-plugin-danmuku<br>整理 DOM 渲染、设置、热力图与 worker | PKG-DANMUKU-04, CORE-14, CORE-18 | renderer/setting/heatmap/worker 职责及资源归属 | mount/icons/设置和 worker 协议保持，销毁无后台工作 | H | todo |
+| PKG-DANMUKU-04 | artplayer-plugin-danmuku<br>整理时钟、队列与轨道调度 | PKG-DANMUKU-03, CORE-10 | danmuku 调度器和确定性时钟测试 | seek/暂停/倍率/长时间运行无顺序和碰撞回归 | H | done |
+| PKG-DANMUKU-05 | artplayer-plugin-danmuku<br>整理 DOM 渲染、设置、热力图与 worker | PKG-DANMUKU-04, CORE-14, CORE-18 | renderer/setting/heatmap/worker 职责及资源归属 | mount/icons/设置和 worker 协议保持，销毁无后台工作 | H | doing |
 | PKG-DANMUKU-06 | artplayer-plugin-danmuku<br>迁移 TS 与公开声明 | PKG-DANMUKU-05, ENG-04, ENG-06 | 自有模块、worker 消息、option/item/result 类型 | 旧参数、扩展字段和事件消费通过，vendored 边界清楚 | H | todo |
 | PKG-DANMUKU-07 | artplayer-plugin-danmuku<br>弹幕能力稳定性验收 | PKG-DANMUKU-06 | 负载/渲染/资源对比及 mask 可依赖的稳定边界 | 在试点核心中旧插件 API 与关键帧路径通过 | H | todo |
 | PKG-DANMUKU-08 | artplayer-plugin-danmuku<br>完成新旧核心与组合验收 | PKG-DANMUKU-07, CORE-22 | 最终核心/旧核心、mask/fullscreen/PiP 组合报告 | 性能无未解释退化，反复装卸无累计资源 | H | todo |
@@ -556,6 +556,7 @@
 - PKG-DANMUKU-01: [记录](baselines/danmuku-release.json) [记录](baselines/danmuku-contract.md) [记录](baselines/danmuku-contract-validation.json) [记录](changes/2026-09-13-PKG-DANMUKU-01-contracts.md)
 - PKG-DANMUKU-02: [记录](changes/2026-09-13-PKG-DANMUKU-02-controlled-failures.md) [记录](baselines/danmuku-failures-validation.json) [记录](changes/2026-09-13-PKG-DANMUKU-02-browser-baseline.md) [记录](baselines/danmuku-browser-validation.json)
 - PKG-DANMUKU-03: [记录](changes/2026-09-13-PKG-DANMUKU-03-input.md) [记录](baselines/danmuku-input-validation.json)
+- PKG-DANMUKU-04: [记录](changes/2026-09-13-PKG-DANMUKU-04-scheduler.md) [记录](baselines/danmuku-scheduler-validation.json)
 - PKG-CANVAS-01: [记录](changes/2026-09-12-PKG-CANVAS-01-contract.md) [记录](baselines/canvas-contract.md) [记录](baselines/canvas-release.json) [记录](canvas-validation.md) [记录](baselines/canvas-contract-validation.json)
 - PKG-CANVAS-02: [记录](changes/2026-09-12-PKG-CANVAS-02-tests.md) [记录](baselines/canvas-behavior-validation.json) [记录](canvas-validation.md)
 - PKG-CANVAS-03: [记录](changes/2026-09-12-PKG-CANVAS-03-lifecycle.md) [记录](baselines/canvas-lifecycle-validation.json) [记录](canvas-validation.md)
@@ -1,5 +1,16 @@
 # 进度与证据

+## PKG-DANMUKU-04 时钟、队列与轨道调度完成
+
+拆分scheduler/queue/worker-client，修复多RAF、同毫秒请求串线、取消后续写、
+节点重复分配、异步拒绝及恢复重入；复审修复03引入的NaN兼容回归。
+源码/main/legacy各104联合测试、三格式共198真实浏览器项及60次额外密集场景通过；
+完整构建、lint通过。关闭ASYNC-01/TRACK-01，Settings/heatmap/完整TS/长负载仍待后续。
+见[变更](changes/2026-09-13-PKG-DANMUKU-04-scheduler.md)及[机器证据](baselines/danmuku-scheduler-validation.json)。
+228项：143 done、15 doing、70 todo；05进入实施。
+没有推送或发布。
+
+
 ## PKG-DANMUKU-03 输入、解析和配置源码完成

 拆分input/config/XML parser模块，修复过期替换、加载拒绝、资源清理、time0、函数配置
@@ -232,7 +232,8 @@
 | DANMUKU-CONFIG-01 | resolved / 已复现 | Danmuku JSON configuration comparison ignores a replacement filter function | PKG-DANMUKU-02, PKG-DANMUKU-03 |
 | DANMUKU-CLEANUP-01 | open / 已复现 | Danmuku removes a different resize callback and retains the settings lock timer on destroy | PKG-DANMUKU-02, PKG-DANMUKU-05 |
 | DANMUKU-TYPE-02 | open / 源码/产物事实 | Danmuku id, icons, Slider steps, heatmap points and partial configuration drift from declarations | PKG-DANMUKU-05, PKG-DANMUKU-06 |
-| DANMUKU-ASYNC-01 | open / 已复现 | Danmuku asynchronous input, worker replies and pending visibility have unverified failure and cancellation paths | PKG-DANMUKU-02, PKG-DANMUKU-03, PKG-DANMUKU-04, PKG-DANMUKU-05 |
+| DANMUKU-ASYNC-01 | resolved / 已复现 | Danmuku asynchronous input, worker replies and pending visibility have unverified failure and cancellation paths | PKG-DANMUKU-02, PKG-DANMUKU-03, PKG-DANMUKU-04, PKG-DANMUKU-05 |
 | DANMUKU-HEATMAP-01 | open / 已复现 | Danmuku heatmap sampling can become zero and points/instance ownership need browser validation | PKG-DANMUKU-02, PKG-DANMUKU-05 |
 | DANMUKU-SOURCE-01 | open / 已复现 | Danmuku registry Git associations differ from releases and static icon provenance remains incomplete | PKG-DANMUKU-09 |
-| DANMUKU-TRACK-01 | open / 已复现 | Native simultaneous fixed Danmuku comments can overlap with duplicate start loops and repeated Worker IDs | PKG-DANMUKU-04, PKG-DANMUKU-05, PKG-DANMUKU-07 |
+| DANMUKU-TRACK-01 | resolved / 已复现 | Native simultaneous fixed Danmuku comments can overlap with duplicate start loops and repeated Worker IDs | PKG-DANMUKU-04, PKG-DANMUKU-05, PKG-DANMUKU-07 |
+| DANMUKU-INPUT-02 | resolved / 已复现 | Intermediate explicit-zero correction regressed accepted NaN timestamp fallback | PKG-DANMUKU-04 |
@@ -5106,7 +5106,9 @@
        "refactor/changes/2026-09-13-PKG-DANMUKU-02-browser-baseline.md",
        "refactor/baselines/danmuku-browser-validation.json",
        "refactor/changes/2026-09-13-PKG-DANMUKU-03-input.md",
-        "refactor/baselines/danmuku-input-validation.json"
+        "refactor/baselines/danmuku-input-validation.json",
+        "refactor/changes/2026-09-13-PKG-DANMUKU-04-scheduler.md",
+        "refactor/baselines/danmuku-scheduler-validation.json"
      ],
      "compatibleResolution": "Track and release exact subscription and timer ownership across settings, renderer and instances.",
      "closureCriteria": "Repeated lifecycle and pending settings actions leave no owned subscriptions, timers or late DOM writes."
@@ -5132,7 +5134,7 @@
      "id": "DANMUKU-ASYNC-01",
      "title": "Danmuku asynchronous input, worker replies and pending visibility have unverified failure and cancellation paths",
      "confirmation": "reproduced",
-      "status": "open",
+      "status": "resolved",
      "owners": [
        "PKG-DANMUKU-02",
        "PKG-DANMUKU-03",
@@ -5148,10 +5150,20 @@
        "refactor/changes/2026-09-13-PKG-DANMUKU-02-browser-baseline.md",
        "refactor/baselines/danmuku-browser-validation.json",
        "refactor/changes/2026-09-13-PKG-DANMUKU-03-input.md",
-        "refactor/baselines/danmuku-input-validation.json"
+        "refactor/baselines/danmuku-input-validation.json",
+        "refactor/changes/2026-09-13-PKG-DANMUKU-04-scheduler.md",
+        "refactor/baselines/danmuku-scheduler-validation.json"
      ],
      "compatibleResolution": "Reproduce load ordering, Bilibili rejection and late worker/visibility paths before defining operation ownership.",
-      "closureCriteria": "Failures settle, obsolete results cannot alter new queues or destroyed instances, and worker resources are released with browser evidence."
+      "closureCriteria": "Failures settle, obsolete results cannot alter new queues or destroyed instances, and worker resources are released with browser evidence.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-13-PKG-DANMUKU-04-scheduler.md",
+        "refactor/baselines/danmuku-scheduler-validation.json",
+        "test/danmuku-scheduler.test.js",
+        "test/danmuku-worker-client.test.js",
+        "test/browser/danmuku-scheduler.spec.js"
+      ],
+      "resolutionRationale": "Task03 input/parser settlement and task04 worker/visibility ownership prevent stale continuation, including recovery reentry; final native matrices verify worker disposal. Settings/heatmap cleanup remains separately open."
    },
    {
      "id": "DANMUKU-HEATMAP-01",
@@ -5194,7 +5206,7 @@
      "id": "DANMUKU-TRACK-01",
      "title": "Native simultaneous fixed Danmuku comments can overlap with duplicate start loops and repeated Worker IDs",
      "confirmation": "reproduced",
-      "status": "open",
+      "status": "resolved",
      "owners": [
        "PKG-DANMUKU-04",
        "PKG-DANMUKU-05",
@@ -5204,10 +5216,42 @@
        "refactor/changes/2026-09-13-PKG-DANMUKU-02-browser-baseline.md",
        "refactor/baselines/danmuku-browser-validation.json",
        "test/browser/danmuku-baseline.spec.js",
-        "test/danmuku-failures.test.js"
+        "test/danmuku-failures.test.js",
+        "refactor/changes/2026-09-13-PKG-DANMUKU-04-scheduler.md",
+        "refactor/baselines/danmuku-scheduler-validation.json"
      ],
      "compatibleResolution": "Enforce one owned scheduler loop and request correlation before claiming simultaneous native anti-overlap stability; keep strict track geometry tests.",
-      "closureCriteria": "Deterministic duplicate-loop/worker regressions and repeated candidate native simultaneous-load geometry pass without extra nodes or stale state; a later passing old snapshot alone does not close the race."
+      "closureCriteria": "Deterministic duplicate-loop/worker regressions and repeated candidate native simultaneous-load geometry pass without extra nodes or stale state; a later passing old snapshot alone does not close the race.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-13-PKG-DANMUKU-04-scheduler.md",
+        "refactor/baselines/danmuku-scheduler-validation.json",
+        "test/danmuku-scheduler.test.js",
+        "test/danmuku-worker-client.test.js",
+        "test/browser/danmuku-scheduler.spec.js"
+      ],
+      "resolutionRationale": "Single owned loop, correlated IDs and unchanged real geometry algorithm pass deterministic regressions, all native matrices and 60 additional repeated dense cases with strict geometry, request and node counts; broad long-load acceptance remains task07."
+    },
+    {
+      "id": "DANMUKU-INPUT-02",
+      "title": "Intermediate explicit-zero correction regressed accepted NaN timestamp fallback",
+      "confirmation": "reproduced",
+      "status": "resolved",
+      "owners": [
+        "PKG-DANMUKU-04"
+      ],
+      "evidence": [
+        "refactor/changes/2026-09-13-PKG-DANMUKU-04-scheduler.md",
+        "refactor/baselines/danmuku-scheduler-validation.json",
+        "test/danmuku-input.test.js"
+      ],
+      "compatibleResolution": "Preserve old NaN default currentTime+0.5, corrected explicit zero and old Infinity normalization without widening validation.",
+      "closureCriteria": "Frozen history and current candidate numeric comparisons pass, and actual native candidate renders NaN input.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-13-PKG-DANMUKU-04-scheduler.md",
+        "refactor/baselines/danmuku-scheduler-validation.json",
+        "test/browser/danmuku-scheduler.spec.js"
+      ],
+      "resolutionRationale": "Historical source/main/legacy establish old behavior; source/main/legacy final input and native matrices confirm the one-condition correction. Task03 frozen evidence is preserved."
    }
  ]
 }
@@ -3320,11 +3320,14 @@
        "PKG-DANMUKU-03",
        "CORE-10"
      ],
-      "status": "doing",
+      "status": "done",
      "risk": "H",
      "deliverable": "danmuku 调度器和确定性时钟测试",
      "acceptance": "seek/暂停/倍率/长时间运行无顺序和碰撞回归",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-13-PKG-DANMUKU-04-scheduler.md",
+        "baselines/danmuku-scheduler-validation.json"
+      ]
    },
    {
      "id": "PKG-DANMUKU-05",
@@ -3338,7 +3341,7 @@
        "CORE-14",
        "CORE-18"
      ],
-      "status": "todo",
+      "status": "doing",
      "risk": "H",
      "deliverable": "renderer/setting/heatmap/worker 职责及资源归属",
      "acceptance": "mount/icons/设置和 worker 协议保持，销毁无后台工作",