feat: add bounded polling and evidence-based workflow recovery examples

2026-09-18 09:52:35 +08:00
parent a4d9900e2c
commit 9f333b5003
14 changed files with 941 additions and 28 deletions
--- a/docs/06-workflow-spec.md
+++ b/docs/06-workflow-spec.md
@@ -1,6 +1,6 @@
 # Weave 流程编排功能与设计

-> 版本 0.10 · 2026-09-18。首版功能范围已确认。定义结构、发布校验与不可变版本已实现，见[定义格式](api/workflow-definition-format.md)和[发布API](api/workflow-definitions.md)；[实例受理](11-workflow-admission.md)、[结果消费与根推进](12-workflow-runtime.md)、[TIMER与POLL时钟](13-workflow-clock.md)已接入。[信号等待及最终查询竞争](14-workflow-signals.md)已接入内部运行器；[暂停/继续/取消与停止结清](15-workflow-controls.md)已实现内部链路；[人工核查与TASK恢复](16-workflow-recovery.md)已接入内部服务；[POLL跨激活恢复](17-workflow-poll-recovery.md)和[等待恢复](18-workflow-wait-recovery.md)已接入；[实例公共API/SDK](api/workflows.md)已接入；流程任务来源已接入；完整历史及生产验收仍需交付。
+> 版本 0.11 · 2026-09-18。首版功能范围已确认。定义结构、发布校验与不可变版本已实现，见[定义格式](api/workflow-definition-format.md)和[发布API](api/workflow-definitions.md)；[实例受理](11-workflow-admission.md)、[结果消费与根推进](12-workflow-runtime.md)、[TIMER与POLL时钟](13-workflow-clock.md)已接入。[信号等待及最终查询竞争](14-workflow-signals.md)已接入内部运行器；[暂停/继续/取消与停止结清](15-workflow-controls.md)已实现内部链路；[人工核查与TASK恢复](16-workflow-recovery.md)已接入内部服务；[POLL跨激活恢复](17-workflow-poll-recovery.md)和[等待恢复](18-workflow-wait-recovery.md)已接入；[实例公共API/SDK](api/workflows.md)已接入；流程任务来源已接入；历史与状态事件已接入；独立[轮询](examples/workflow-poll.md)/[恢复](examples/workflow-recovery.md)示例已交付，剩余故障见[P4/P5核对](reports/phase-4-5.md)，生产验收仍未完成。

 ## 1. 职责与边界

@@ -49,11 +49,11 @@ Weave 不执行特定业务逻辑，也不把整段业务代码放入平台进
 | `poll_round` | 同一次查询节点激活内的查询轮次；一轮关联一个 Pulse 任务，可包含多次执行尝试 |
 | `signal_id` / 关联键 | 信号去重及匹配指定实例、步骤激活或业务操作 |

-启动时绑定明确的定义版本、参数版本、处理器兼容要求和策略快照。若允许以“当前版本”启动，首次受理时解析并固定；相同幂等键重报仍返回首次绑定的实例。
+启动时绑定明确的定义版本、参数版本、处理器兼容要求和策略快照。当前公共API只接受显式发布版本，不解析latest别名；相同幂等键重报仍返回首次绑定的实例。

 初次启动的幂等键至少在命名空间和操作类型内唯一。同键不同语义输入必须冲突；不因新定义发布就生成另一份流程。

-## 4. 建议状态模型
+## 4. 状态模型

 流程状态与任务状态分别管理，不能用“最后一个任务成功”替代整个流程的成功条件。

@@ -69,7 +69,7 @@ Weave 不执行特定业务逻辑，也不把整段业务代码放入平台进

 存在未知副作用时不能进入一个暗示“全部已结清”的终态。建议异常核查优先显示为 `NEEDS_REVIEW`，同时保留取消意图及每个分支的真实状态；状态汇总优先级在协议评审中固定。

-暂停建议用独立持久化标记 `paused` 与控制版本表达，不覆盖上述执行状态：实例可以同时显示“已暂停”和“有任务执行中”或“待核查”。恢复仅解除暂停，不自动解除核查或撤销取消。具体字段与汇总展示规则仍待协议评审。
+暂停建议用独立持久化标记 `paused` 与控制版本表达，不覆盖上述执行状态：实例可以同时显示“已暂停”和“有任务执行中”或“待核查”。恢复仅解除暂停，不自动解除核查或撤销取消。具体字段见[实例接口](api/workflows.md)，暂停与核查分别解除。

 步骤单独保存等待前置条件、等待任务、等待信号/时间、完成、失败、跳过或待核查等阶段及状态版本。步骤任务排队不代表业务已经运行；详情应展示 Pulse 的实际执行阶段。

@@ -84,7 +84,7 @@ Weave 不执行特定业务逻辑，也不把整段业务代码放入平台进
 | 启动流程 | 启动幂等记录、实例与首批激活步骤、对应 Pulse 任务、状态事件 |
 | 保存任务结果 | Pulse 任务/尝试结果、额度释放、结果事件及内部交付记录 |
 | 接续任务结果 | 核对实例与步骤激活、消费去重、步骤变化、流程推进、后续任务或等待记录、内部事件处理确认 |
-| 建立定时等待 | 步骤等待条件、截止时间、对应的 Pulse 内部定时任务 |
+| 建立定时等待 | 步骤等待条件、截止时间、weave_pending_advances持久检查点 |
 | 接收信号 | 幂等记录、信号内容与身份、持久化待处理记录 |
 | 消费信号 / 定时唤醒 | 校验等待条件与状态版本、消费标记、流程推进、后续任务创建 |
 | 查询轮次推进 | 校验暂停/取消、轮次/时间预算，创建唯一轮次记录与对应任务，或保存下一次唤醒 |
@@ -113,9 +113,9 @@ Weave 不执行特定业务逻辑，也不把整段业务代码放入平台进
 - 信号关联必须能区分具体业务操作，不能只按“审核通过”等类型匹配，避免旧业务批次、旧步骤或旧恢复轮次的信号误用。
 - 信号受理成功只表示已可靠保存，消费与步骤推进状态可另外查询。

-定时等待使用已保存的截止时间和内部定时任务。定时唤醒由平台执行角色处理，不需要业务 Worker 长期占用连接槽位。任务结果与后续等待消费仍遵守幂等和事务规则。
+定时等待使用已保存的截止时间和weave_pending_advances检查点。定时唤醒由平台执行角色处理，不需要业务 Worker 长期占用连接槽位。任务结果与后续等待消费仍遵守幂等和事务规则。

-信号、超时与取消竞争时，按等待记录的状态版本原子决定结果。采用信号持久化受理时间与等待截止时间判断是否按时到达，不能因消费积压把已经按时受理的信号误判为超时；截止点的包含规则待协议冻结。取消另一条唤醒路径后，迟到事件只留痕，不再次推进。
+信号、超时与取消竞争时，按等待记录的状态版本原子决定结果。采用信号持久化受理时间与等待截止时间判断是否按时到达，不能因消费积压把已经按时受理的信号误判为超时；当前规则要求受理时间严格早于截止，等于截止不视为按时到达。取消另一条唤醒路径后，迟到事件只留痕，不再次推进。

 未匹配信号数量、参数大小、保留时间与等待时限必须有上限。到期清理需要可观测且有明确规则，不能悄悄丢掉仍有效的等待依据。

@@ -123,14 +123,14 @@ Weave 不执行特定业务逻辑，也不把整段业务代码放入平台进

 **功能已确认**：查询成功但外部业务仍在处理中，由 Weave 等待后发起下一轮；查询请求失败，由 Pulse 在当前轮次内按安全策略重试。达到轮次或总时限上限后转人工核查，不直接认定外部业务失败。

-以下为实现建议，具体字段与边界待技术评审：
+以下约束已按[定义格式](api/workflow-definition-format.md)和[时钟约定](13-workflow-clock.md)冻结：

-| 内容 | 建议约束 |
+| 内容 | 当前约束 |
 | --- | --- |
 | 查询目标 | 固定查询处理器、版本和外部业务操作标识；恢复查询不能重新调用提交接口 |
 | 轮次上限 | `max_rounds` 为有限正整数；创建轮次记录与查询任务时原子计数，不因重复事件或重启重复增加 |
 | 总时限 | 从节点激活时固定 `deadline_at`；建议同时设置轮次与时间上限，先到者阻止新一轮 |
-| 查询间隔 | 建议从上一轮完成且结果仍为处理中时计算下一次时间，可设有上限的退避与抖动；不按错过的间隔集中补跑 |
+| 查询间隔 | 从上一轮PENDING结果的可靠事件时间计算固定间隔；业务轮间不支持抖动或变长退避，不按错过的间隔集中补跑 |
 | 单轮执行重试 | Pulse 使用独立且有限的尝试预算，自动重试保持该轮任务 ID；受节点剩余时限约束 |
 | 结果映射 | 明确区分处理中、业务确认成功、业务确认失败和需要核查；未知值不能默认为成功或继续循环 |

@@ -152,13 +152,13 @@ Weave 不执行特定业务逻辑，也不把整段业务代码放入平台进

 **功能已确认**：暂停阻止新步骤推进，保留已完成进度，继续接收在途结果与外部回执；继续操作从持久化进度恢复。暂停不表示已经停止外部业务操作。

-以下细则已按[控制运行约定](15-workflow-controls.md)冻结并实现内部链路，公共HTTP/SDK仍待交付：
+以下细则已按[控制运行约定](15-workflow-controls.md)冻结并实现内部链路，[公共HTTP/SDK](api/workflows.md)也已接入：

 - 暂停与继续带预期控制版本、稳定操作身份、操作人及原因；状态与审计一起提交。新步骤创建必须原子检查控制版本。
 - 建议暂停还阻止关联任务的新领取、开始授权和执行重试，包含已经创建但尚未开始的任务。由 Pulse 的通用执行门控与 Weave 控制状态同事务更新，领取/开始时读取权威门控，避免仅暂停流程循环却继续派发旧队列任务。
 - 暂停前已获得开始授权的尝试仍可运行、续租和上报，保留时限与安全约束。暂停与开始竞争按事务顺序决定；“暂停成功”只表示门控已持久化，不表示所有在途请求已停止。
 - 在暂停期间可靠保存任务结果、信号和到期事实，必要时进入核查或结清已有工作；不创建新的业务步骤或查询轮次。即使内部事件已确认消费，也要保存待续推进状态，避免恢复后无事件可推进。
- 建议暂停不延长原业务截止时间，查询节点、任务时限与信号有效期继续计时。恢复时先核对已受理结果、信号和原截止时间，不能把过期查询重新激活；时间策略在协议冻结前确认。
+- 建议暂停不延长原业务截止时间，查询节点、任务时限与信号有效期继续计时。恢复时先核对已受理结果、信号和原截止时间，不能把过期查询重新激活；当前等待、查询和任务都保留原截止。
 - 恢复按配额和推进预算处理积压，不重置已用查询轮次和执行尝试，不补发每一个错过的查询时间点。恢复不改变原流程版本，不清除取消或待核查条件。

 ### 7.2 执行失败与人工恢复
@@ -202,7 +202,7 @@ Weave 不执行特定业务逻辑，也不把整段业务代码放入平台进

 旧定义、参数解释与处理器版本在仍有运行实例时必须保持可用，或明确进入可观测的版本不兼容等待；升级不能悄悄把旧实例转到新逻辑。

-功能范围已确认。实施前仍需评审：SDK 构建 API、定义 Schema、分支表达式、并行失败策略、暂停门控及计时规则、轮询预算与截止边界、人工恢复身份模型、协议字段、资源上限与保留周期。验收覆盖 [生产验收](05-production-acceptance.md) 的流程场景，尤其是暂停竞争、轮次恢复、查询与回执竞争及版本发布。
+功能范围已确认。SDK构建类型、定义Schema、分支表达式、并行失败策略、暂停门控、轮询预算、恢复身份和协议限制已在对应实现手册中冻结。保留/归档、生产参数、精确故障矩阵及容量仍需P6/P7交付，不能由已有正常路径反推完成。验收覆盖 [生产验收](05-production-acceptance.md) 的流程场景，尤其是暂停竞争、轮次恢复、查询与回执竞争及版本发布。

 ## 10. 决策记录