feat: add bounded task priority and fair application dispatch

2026-09-17 18:45:54 +08:00
parent 958b4a8cea
commit 309ed75666
42 changed files with 1277 additions and 61 deletions
--- a/docs/07-data-model.md
+++ b/docs/07-data-model.md
@@ -1,6 +1,6 @@
 # 数据模型与实现基线

-更新：2026-09-17。数据库统一禁止外键。当前已实现任务执行、安全重试、运行中取消、计划调度、队列限速/背压和应用配额；公平性、订阅及流程编排继续开发。
+更新：2026-09-17。数据库统一禁止外键。当前已实现任务执行、安全重试、运行中取消、计划调度、队列限速/背压和应用配额；优先级及节点公平领取已实现；订阅及流程编排继续开发。

 ## 1. 模块与依赖

@@ -135,8 +135,14 @@ P2 服务端已新增会话隔离、两步派发、租约、并发许可、结

 ## 13. 显式资源键许可

-000011_keyed_concurrency 增加 Task.ConcurrencyKey / ConcurrencyKeyDigest、Attempt.ConcurrencyToken、WorkerSession.ConcurrencyKeys，共四个中文注释与 SQL COMMENT 字段。历史值分别为空/空、零和 false，原 BusinessKey 语义不变；33 个实体、273 个直接声明的持久化字段，最终外键数保持零。
+000011_keyed_concurrency 增加 Task.ConcurrencyKey / ConcurrencyKeyDigest、Attempt.ConcurrencyToken、WorkerSession.ConcurrencyKeys，共四个中文注释与 SQL COMMENT 字段。历史值分别为空/空、零和 false，原 BusinessKey 语义不变；截至 000011 为 33 个实体、273 个直接声明的持久化字段，最终外键数保持零。

 资源限制复用 ConcurrencyLimit：scope_key=key，key_digest 为域分隔 SHA-256，命名空间内唯一；每键最大许可固定 1。原始 UTF-8 字节精确匹配，不依赖 MySQL 的文本排序规则。一个有键尝试持有队列和资源键两条 Permit，应用活跃尝试只计一次；续租、释放、恢复与状态同事务完成。

 键行 Revision 在领取和释放时递增，领取后的值保存到 Attempt.ConcurrencyToken；同尝试重连不改变序号，资源行不得删除或重置。达到整数边界时拒绝新领取，禁止回绕。SDK 交付序号，资源端负责原子比较与业务幂等；历史未知效果与执行许可释放分别维护。字段、升级、调用和异常语义见 [资源键契约](api/keyed-concurrency.md)。
+
+## 14. 任务优先级和节点公平领取
+
+000012_dispatch_priority 开放既有 Priority，范围 0–9，并增加对应 CHECK。新增只读生成列 DispatchAt（AvailableAt 减 Priority 乘30秒）及 `(namespace_id,queue_id,state,dispatch_at,available_at,id)` 排序索引；历史默认优先级 0 的排序时间等于 AvailableAt。Generated 字段随退避和恢复自动重新计算，不允许独立写入。33 个实体、274 个直接声明的持久化字段全部保留中文注释，新增 SQL 字段和 Priority 的 COMMENT 同步更新，无外键。
+
+派发先检查实际到期、截止、能力、门控和资源键，再按排序时间选择。节点公平领取池根据认证后的 ApplicationID 分组，再按命名空间/队列轮转；内存队列和短期空探测缓存可在重启后重建，不保存授权事实。详细约束、SDK 和升级步骤见 [优先级与公平派发](api/priority-and-fairness.md)。
--- a/docs/08-development-plan.md
+++ b/docs/08-development-plan.md
@@ -27,7 +27,7 @@
 | P0 基础与数据模型 | Go workspace、独立 SDK module、公共/Pulse/Weave 模型、MySQL 迁移、配置、健康检查 | 编译/竞态/静态检查；真实 MySQL 建表、隔离、唯一性、预算、不可变版本、迁移失败防护；SDK 健康调用 | 已完成并通过阶段回归（见 P0 报告） |
 | P1 任务受理闭环 | 应用凭据与作用域权限、队列、幂等提交、查询、待执行取消、受理事件；SDK 客户端 | API/SDK 创建查询闭环；重复键与内容冲突、响应未确认重报、跨命名空间拒绝、参数边界 | 已完成并通过阶段回归（见 P1 报告；真实断路/提交 ACK 丢失注入留后续故障阶段） |
 | P2 Worker 执行闭环 | WSS 接入、能力/容量、领取与开始、租约、续租、结果确认、排空与恢复；Worker SDK | 真 Worker 执行；失联/重连/重复确认/旧尝试拒绝；业务效果未知转核查；节点故障接管 | 已完成并通过阶段回归：服务端、自动 SDK、历史查询、完整 Schema 与真实进程强杀恢复；测试拓扑和剩余生产故障矩阵见 P2 验收报告 |
-| P3 Pulse 完整能力 | 安全重试、延时、Cron/固定间隔、漏跑策略、计划版本、运行中取消、并发许可、配额/背压、可靠结果订阅 | 多实例领取/触发竞争、重试上限、取消竞争、队列隔离、积压恢复、事件重复交付 | 进行中：安全重试、计划调度、运行中取消、队列控制/限速/积压背压、跨命名空间应用配额、显式资源键许可及 SDK 场景已实现并通过全量回归；优先级/公平性和可靠订阅待开发 |
+| P3 Pulse 完整能力 | 安全重试、延时、Cron/固定间隔、漏跑策略、计划版本、运行中取消、并发许可、配额/背压、可靠结果订阅 | 多实例领取/触发竞争、重试上限、取消竞争、队列隔离、积压恢复、事件重复交付 | 进行中：安全重试、计划调度、运行中取消、队列控制/限速/积压背压、跨命名空间应用配额、显式资源键许可及 SDK 场景已实现并通过全量回归；优先级及节点公平派发已实现并通过全量回归；可靠订阅待开发 |
 | P4 Weave 主流程 | SDK 定义构建与发布校验、实例、顺序/分支/结构化并行汇合、信号/定时等待、版本绑定 | 重启接续、早到/重复信号、并行竞争、内部事件重放、发布版本兼容；端到端通用流程 | 待开发 |
 | P5 Weave 恢复与查询 | 有界查询、暂停继续、取消、人工核查恢复、控制门控与审计 | 轮次与尝试独立预算；暂停/开始/回执/超时竞争；恢复保留预算；未知结果不盲目重复 | 待开发 |
 | P6 生产验证与运维 | 完整监控、凭据轮换、备份恢复、滚动升级、运行手册、可复现负载和故障工具 | 对照生产验收清单执行，报告环境/指标/遗留项；容量、RPO/RTO 按真实拓扑验证 | 待开发 |
@@ -47,6 +47,7 @@ SDK、文档与示例随 P1–P5 同步开发，P7 是全量核对，不是最
 | 队列限速与背压 | 暂停 → 满额拒绝 → 原回执核对 → 释放空间 → 限速执行 | P3，已实现完整示例 |
 | 跨命名空间应用配额 | first 受理 → second 全局满额 → 释放 → 原键成功 → 恢复配置 | P3，已实现完整示例 |
 | 跨队列共享资源 | 两队列同键 → 一个有效许可 → 递增序号 → 资源端拒绝旧写入 | P3，已实现完整示例 |
+| 优先级与应用隔离 | 近同时到期按优先级 → 旧任务等待补偿 → 应用/队列轮转 | P3，已实现完整示例 |
 | 并行生成结果 | 发布流程 → 并行执行 → 汇合 → 完成 | P4 |
 | 审核与外部回执 | 提交流程 → 等待信号 → 授权信号注入 → 继续 | P4 |
 | 外部作业轮询 | 提交一次 → 有界查询处理中状态 → 回执或最终结果 → 超限核查 | P5 |
@@ -86,6 +87,7 @@ SDK、文档与示例随 P1–P5 同步开发，P7 是全量核对，不是最
 - [P3 队列资源控制回归](reports/phase-3-queue-resources.md)
 - [P3 应用共享配额回归](reports/phase-3-application-resources.md)
 - [P3 资源键许可回归](reports/phase-3-keyed-concurrency.md)
+- [P3 优先级和公平派发回归](reports/phase-3-priority-fairness.md)
 - [P2 服务端阶段记录](reports/phase-2-server.md)
 - [P2 SDK 协议阶段记录](reports/phase-2-sdk-protocol.md)
 - [P2 自动 Worker 运行器记录](reports/phase-2-worker-runtime.md)
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,7 +2,7 @@

 - 文档版本：0.2
 - 整理日期：2026-09-17
- 阶段：P0–P2 已通过阶段验收；P3 安全重试、计划调度、运行中取消、队列资源控制和应用共享配额已通过回归，资源键许可及真实进程恢复已通过全量回归，数据库已改为无外键，P3–P7 继续推进，尚未完成全平台生产验收
+- 阶段：P0–P2 已通过阶段验收；P3 安全重试、计划调度、运行中取消、队列资源控制和应用共享配额已通过回归，资源键许可及真实进程恢复已通过全量回归，优先级/节点公平派发及真实隔离场景已通过全量回归，数据库已改为无外键，P3–P7 继续推进，尚未完成全平台生产验收
 - 适用范围：Orbit 统一平台，包含 Pulse 任务调度模块、Weave 流程编排模块与公共能力。平台面向多个业务系统复用。

 ## 阅读顺序
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -14,6 +14,7 @@
 | `/v1/queues` 创建、查询及 `:configure` 控制 | 已实现队列并发、开始速率、积压背压与暂停/恢复 | [队列接口与 SDK 场景](queues.md) |
 | `/v1/application/resources` 查询及 `:configure` 管理 | P3 已实现跨命名空间应用配额 | [应用配额与 SDK 场景](application-resources.md) |
 | 任务 `concurrency_key` 与尝试 `concurrency_token` | P3 已实现跨队列资源键互斥 | [资源键接口与 SDK 场景](keyed-concurrency.md) |
+| 任务 `priority` 与节点领取池 | P3 已实现有界优先级加速、应用/队列轮转 | [优先级与公平派发](priority-and-fairness.md) |
 | 凭据校验与初始化 CLI | P1 已实现 | [鉴权](authentication.md) |
 | `/v1/worker/connect` | P2 已实现并通过阶段验收 | [Worker 契约](worker.md)、[Schema](worker-schema.md) |
 | 任务冻结策略与 Worker `retryable` | P3 安全重试已实现 | [安全重试](retries.md) |
--- a/docs/api/application-resources.md
+++ b/docs/api/application-resources.md
@@ -158,4 +158,4 @@ unfinished=0 active=0 pending_starts=0

 统一顺序为认证 → Worker 会话（需要时）→ 应用额度 → 队列 → 任务/尝试 → 许可。额度与身份分表，避免把认证共享锁升级为排他锁。恢复和调度对忙碌额度行使用 SKIP LOCKED，保留后续扫描；不采用全表计数参与每次领取。额度配置审计记录在发起凭据的命名空间，应用标识明确保存。

-同一应用共享一条额度行，严格额度会使该应用的相关短事务串行化。当前范围是同一 MySQL 主库；未宣称跨库原子配额或百万租户性能，后续容量验证需测单个高流量应用的锁等待、租约续期和恢复延迟。业务键许可、公平派发、可靠订阅与完整生产容量/故障验收继续按开发计划推进。真实验证记录见 [应用配额回归](../reports/phase-3-application-resources.md)。
+同一应用共享一条额度行，严格额度会使该应用的相关短事务串行化。当前范围是同一 MySQL 主库；未宣称跨库原子配额或百万租户性能，后续容量验证需测单个高流量应用的锁等待、租约续期和恢复延迟。[资源键许可](keyed-concurrency.md) 和 [优先级/节点公平领取](priority-and-fairness.md) 已接入；可靠订阅与完整生产容量/故障验收继续按开发计划推进。真实验证记录见 [应用配额回归](../reports/phase-3-application-resources.md)。
--- a/docs/api/keyed-concurrency.md
+++ b/docs/api/keyed-concurrency.md
@@ -114,4 +114,4 @@ resource_writes=2 stale_write_rejected=true worker_drained=true

 000011 为历史任务填空键/空摘要、历史尝试填零序号、历史会话填 false，不改变原 business_key。新增四个模型字段均有中文注释和 SQL COMMENT，实体数仍为 33；数据库最终外键数为零。

-当前基于一个 MySQL 主库及应用额度锁串行化事务，资源键记录随不同键数量持续增长。尚未提供可调的每键并发大于 1、资源管理/清理接口、优先级公平性或生产容量结论。验证证据见 [本阶段报告](../reports/phase-3-keyed-concurrency.md)。
+当前基于一个 MySQL 主库及应用额度锁串行化事务，资源键记录随不同键数量持续增长。尚未提供可调的每键并发大于 1、资源管理/清理接口、生产容量结论；[优先级与节点公平派发](priority-and-fairness.md) 已补齐。验证证据见 [本阶段报告](../reports/phase-3-keyed-concurrency.md)。
--- a/docs/api/priority-and-fairness.md
+++ b/docs/api/priority-and-fairness.md
@@ -0,0 +1,117 @@
+# 任务优先级与公平派发
+
+状态：P3 已实现。优先级使用持久化任务字段，节点公平派发控制领取机会；任务执行权、应用配额与两类并发许可仍由 MySQL 事务决定。平台不增加缓存或消息队列服务。
+
+## 1. 任务优先级
+
+在 [POST /v1/tasks](tasks.md) 或 [计划版本的 definition.task](schedules.md) 中指定：
+
+| 字段 | 类型 / 默认 | 含义 |
+| --- | --- | --- |
+| priority | 可选 JSON 整数，默认 0，范围 0–9 | 受理时固定的任务优先级；每级最多取得 30 秒排序优势 |
+
+负数、超过 9、浮点表示、字符串、bool 和 null 均返回 HTTP 400 / INVALID_ARGUMENT。Go SDK 对应 `Priority int16`。零值省略以保留旧请求摘要；任务详情、摘要和 Worker 派发在非零时返回 priority。查询到零或省略都表示普通优先级。
+
+权限、请求头、提交结果、受理幂等、取消和截止规则沿用任务接口，没有单独的优先级管理权限或运行中改级接口。相同受理键改变 priority 返回 409 IDEMPOTENCY_CONFLICT。安全重试保持冻结优先级，下一次 available_at 改变时重新计算排序时间；计划触发继承对应不可变版本里的 priority。
+
+```json
+{
+  "queue_id":"11111111111111111111111111111111",
+  "handler":"object.prepare",
+  "handler_version":"v1",
+  "payload_version":"v1",
+  "payload":{"object_ref":"objects/example","operation_ref":"prepare-001"},
+  "priority":9
+}
+```
+
+成功响应仍是任务接口的完整信封，首次 201、重复受理 200；任务对象包含 `"priority":9`。提交确认不代表已执行。
+
+## 2. 排序与等待补偿
+
+同一队列、与当前 Worker 版本和能力匹配且满足门控/租约/许可条件的到期任务，按下面三个键升序排列：
+
+1. `dispatch_at = available_at - priority × 30 秒`。
+2. available_at。
+3. task_id（只用于确定性打破同时间相等，不表示业务顺序）。
+
+dispatch_at 为数据库生成的只读字段，并有相应派发索引；它不对外提供执行授权。真正的最早执行时间始终是 available_at，派发仍检查截止、次数、门控、能力和资源键占用。
+
+| 两条已就绪任务 | 先选择的任务 |
+| --- | --- |
+| A：0 级、5 秒前到期；B：9 级、刚到期 | B，获得 270 秒排序优势 |
+| A：0 级、271 秒前到期；B：9 级、刚到期 | A，旧任务的等待已超过最大优势 |
+| A：0 级、已到期；B：9 级、1 小时后才到期 | A，B 不具备领取资格 |
+| 同一优先级、不同 available_at | 更早到期者 |
+
+由此限制新高优先级工作插队的时间优势，避免纯粹按优先级排序造成持续饥饿。**270 秒不是最大排队时长**：旧积压、队列/应用额度、兼容 Worker、暂停、共享资源和每个任务执行时长仍影响等待。已被预占或正在运行的任务不被抢占；没有全局 FIFO 或跨队列优先级比较。
+
+## 3. 节点内应用与队列轮转
+
+Worker 连接不再各自直接并发发起一批数据库领取。节点采用有界领取池：
+
+| 约束 | 当前开发基线 |
+| --- | --- |
+| 同时执行的领取 SQL 操作 | 每节点最多 4 个 |
+| 一个应用同时在途的领取 | 每节点最多 1 个，其他应用可以继续领取 |
+| 待处理和在途领取请求合计 | 每节点最多 128 个 |
+| 每个连接未完成领取请求 | 最多 1 个 |
+| 选择顺序 | 活跃应用轮转 → 该应用的队列轮转 → 队列内连接请求顺序 |
+| 单个连接派发节奏 | 每个扫描周期最多 4 次领取，当前周期 1 秒 |
+
+应用身份来自服务端验证过的命名空间归属，客户端不能通过增加命名空间或伪造应用字段分散公平组。一个应用增加队列或 Worker 数量，也不会在所有应用都持续有待处理请求时得到额外轮次。某个应用没有请求或已有在途领取时，其他应用继续使用空闲池容量。
+
+同命名空间、队列、精确处理器能力集合及资源键支持声明的空领取结果，在本节点合并一个扫描周期，缓存最多 128 项。不同能力不共用空结果。缓存过期重新查询；任务新到达或容量释放可能多等待一个周期。这只抑制重复探测，不能据此授权任务或更改持久化状态。
+
+领取在后台有界执行，WS 控制循环继续接收心跳、Start、续租、Finish 和排空。关闭节点时取消待领取操作并等待在途收尾；已提交但尚未发送的预占仍由数据库租约恢复。任务处理器运行在业务 Worker，完全不占这个 SQL 领取池。
+
+这是**节点内领取机会的公平性**。各节点分别轮转，没有宣称跨节点完全相等吞吐、全局权重或严格最大延迟。跨节点执行并发和开始额度仍由已实现的 [应用配额](application-resources.md) 与 [队列控制](queues.md) 原子保证。连接接入总上限仍为每节点 128；该机制不提供每应用连接预留，也不代替请求层限流或生产容量规划。
+
+## 4. SDK 完整场景
+
+源码：[priority/main.go](../../sdk/go/examples/priority/main.go)。创建专用队列，先按 0、9、4 的顺序提交三条任务，再启动容量为 1 的自动 Worker；三条任务在近同时到期的条件下按 9、4、0 执行，每条只有一次尝试。
+
+从仓库根目录准备专用开发数据库，设置 ORBIT_MYSQL_DSN 和 `ORBIT_HTTP_ADDR=127.0.0.1:8080` 后：
+
+```sh
+go run ./cmd/orbit-migrate up
+go run ./cmd/orbit-admin bootstrap --application priority-example --namespace default \
+  --environment test --queue initial --worker-access --output /tmp/orbit-priority.credentials.json
+go run ./cmd/orbit
+```
+
+凭据需要全部队列范围的 queues:manage、tasks:submit/read、workers:connect/consume。另一个终端执行：
+
+```sh
+cd sdk/go
+ORBIT_URL=http://127.0.0.1:8080 \
+ORBIT_CREDENTIALS_FILE=/tmp/orbit-priority.credentials.json go run ./examples/priority
+```
+
+预期输出：
+
+```text
+submitted_priorities=0,9,4 executed_priorities=9,4,0
+completed=3 attempts_per_task=1 worker_drained=true
+```
+
+示例返回输入对象及精确大整数，不访问外部业务资源。总任务截止为 20 秒，整个场景 25 秒；每次创建独立队列/处理器与任务，正常结束排空，历史保留。异常非零退出并有界收尾。这个短场景演示优先级加速，等待补偿的 271 秒边界由真实数据库夹具验证，不让读者实际等待几分钟。
+
+调用片段（上下文、客户端和队列已初始化）：
+
+```go
+accepted, err := api.SubmitTask(ctx, "prepare-operation-001", orbit.SubmitTaskRequest{
+    QueueID: queueID, Handler: "object.prepare", HandlerVersion: "v1", PayloadVersion: "v1",
+    Payload: json.RawMessage(`{"object_ref":"objects/example"}`), Priority: 9,
+})
+```
+
+在处理器中通过 `e.Task.Priority` 读取冻结值；调度顺序由平台确定，业务 Worker 不应绕过 Start 或自行重排已授权任务。
+
+## 5. 升级与验收边界
+
+停止旧写入节点，应用 000012，再启新版服务。历史任务优先级为 0，生成排序时间等于原 available_at；既有任务、索引和历史保留，新增索引单独建立。优先级限制附 CHECK，generated 字段与 Go 模型均有中文说明，数据库最终仍无外键。
+
+新版 SDK 开始提交非零 priority 前，先升级服务端；旧服务严格拒绝未知输入字段。公开 Worker Schema 已扩展可选 priority，其他语言的严格验证器需同步升级；默认 0 的派发报文保持原形状。
+
+单节点公平领取及真实 MySQL/WSS 故障隔离已纳入回归。多节点不均匀连接分布、混合负载下各应用延迟、SQL 锁等待、海量未来任务扫描及峰值容量在 P6 验收，当前参数不能作为百万租户容量承诺。完整记录见 [本阶段报告](../reports/phase-3-priority-fairness.md)。
--- a/docs/api/queues.md
+++ b/docs/api/queues.md
@@ -144,4 +144,4 @@ unfinished=0 rate_per_second=1 worker_drained=true

 创建命令省略新字段时，幂等摘要保留旧字段集合。旧创建回执不含新字段，SDK 解码为零，只表示历史快照缺少信息，实时配置另行 GetQueue。配置接口是新能力；自动 SDK 已能处理 RATE_LIMITED，进行降额管理前应先升级 Worker。

-本阶段验证见 [资源控制报告](../reports/phase-3-queue-resources.md)。[应用级跨命名空间配额](application-resources.md) 已实现并同时生效。仍需同业务键许可、可配置优先级及应用间公平性、可靠事件积压限制和容量验收；不能用单队列控制替代这些要求。
+本阶段验证见 [资源控制报告](../reports/phase-3-queue-resources.md)。[应用级跨命名空间配额](application-resources.md) 已实现并同时生效。[资源键许可](keyed-concurrency.md) 与 [优先级/节点公平派发](priority-and-fairness.md) 已实现；可靠事件积压限制及跨节点公平负载和容量验收继续推进。
--- a/docs/api/tasks.md
+++ b/docs/api/tasks.md
@@ -25,6 +25,7 @@ P2 进展：服务端执行内核、WSS 与独立自动 Worker SDK 已可产生
 | payload | JSON | 必填 | 非 null JSON，最大 256 KiB；平台不解释业务字段 |
 | business_key | string | 可选 | 最多 191 个 Unicode 字符，无 NUL/换行；用于关联，不提供业务幂等 |
 | concurrency_key | string | 可选，空为关闭 | 1–191 个 Unicode 字符，无控制字符和首尾空白；显式资源互斥键，同命名空间跨队列共享，见 [资源键契约](keyed-concurrency.md) |
+| priority | 整数 | 可选，默认 0 | 0–9，冻结优先级，每级30秒排序优势；不提前延时任务，见 [优先级与公平派发](priority-and-fairness.md) |
 | available_at | time / null | 受理时数据库时间 | 最早可执行时间；必须早于总截止时间，仅允许最多 1 秒的过去时间容差 |
 | start_deadline_at | time / null | 无独立限制 | 必须晚于当前时间，不早于 available_at，不晚于总截止时间 |
 | task_timeout_ms | uint64 | 0 或省略为 86400000 | 从受理时计算的总时限，最大 30 天（2592000000 毫秒） |
--- a/docs/api/worker-schema.md
+++ b/docs/api/worker-schema.md
@@ -35,6 +35,7 @@ ACK 的 body 根据原请求选择：worker.capacity → welcome，worker.resume
 - hello.concurrency_keys 可选且默认 false，未声明时不派发带资源键任务；task.assign.task.concurrency_key 与非零字符串 concurrency_token 必须同时出现。Schema 检查字段配对，SDK 另核验支持声明和键格式，事务维护许可；见 [资源键契约](keyed-concurrency.md)。
 - finish.retryable 为可选布尔值，默认 false；true 仅允许 FAILED，Schema 与服务端都校验。派发任务可带 effect_uncertain=true，表示此前授权执行的效果尚未核实。业务重试条件见 [安全重试](retries.md)。
 - 返回时间使用 UTC RFC 3339，最多微秒精度。验证器应开启 format 断言以校验实际日历日期。
+- task.assign.task.priority 为可选 0–9 整数，零值省略；平台在实际到期后结合等待时间排序，详见 [优先级与公平派发](priority-and-fairness.md)。

 P2 收紧了开发期此前允许的省略控制字段、非规范计数字符串和数组内字段别名。当前 SDK 一直发送完整规范字段，不需迁移；其他自研客户端应按本文件更新。SDK 尚未发布首个版本。将来扩展消息类型或改变字段语义必须同时更新 Schema、服务端、SDK 与兼容回归。

--- a/docs/api/worker.md
+++ b/docs/api/worker.md
@@ -130,7 +130,7 @@ receipt 是原操作的不可变确认；lease 是本次重新核验的执行权

 平台在同一事务中预占应用并发与开始额度、分配队列并发许可、创建尝试、递增任务执行代次和次数、保存 LEASED 与派发事件。领取本身消耗一次 max_attempts 预算，包括最终未获开始授权的尝试，预算不会因重连或过期恢复重置。

-运行中的进程总容量跨其所有旧/新会话统计。声明容量减少、断开连接或重复结果，都不能重复释放额度。已实施队列 max_concurrency、rate_per_second 及未终结任务上限；参数含义、窗口突发、暂停及降额语义见 [队列资源控制](queues.md)。[应用级配额](application-resources.md) 与 [显式资源键许可](keyed-concurrency.md) 同时生效；公平性继续推进。
+运行中的进程总容量跨其所有旧/新会话统计。声明容量减少、断开连接或重复结果，都不能重复释放额度。已实施队列 max_concurrency、rate_per_second 及未终结任务上限；参数含义、窗口突发、暂停及降额语义见 [队列资源控制](queues.md)。[应用级配额](application-resources.md) 与 [显式资源键许可](keyed-concurrency.md) 同时生效；[任务优先级和节点公平领取](priority-and-fairness.md) 已接入。

 同命名空间的 concurrency_key 跨队列互斥，领取事务同时保存键许可和 concurrency_token；原 business_key 仅追踪。没有声明 concurrency_keys 的 Worker 不领取带键任务。资源端需用单调序号和操作幂等保护实际写入，平台无法撤回外部已发出的请求；未知结果释放执行许可并保留核查状态，详细边界和升级顺序见资源键契约。

@@ -147,8 +147,8 @@ receipt 是原操作的不可变确认；lease 是本次重新核验的执行权

 ## 6. 连接保护与当前边界

-当前节点上限 128 条 Worker 连接；每连接入站队列 4 帧、出站队列 8 帧，派发保留 ACK 缓冲空间，每秒最多发起 4 次新派发尝试。读空闲期限 60 秒、写期限 5 秒、单个数据库控制操作期限 8 秒。慢消费者导致连接关闭时，已提交状态仍由稳定身份恢复。
+当前节点上限 128 条 Worker 连接；每连接入站队列 4 帧、出站队列 8 帧，派发保留 ACK 缓冲空间，每个扫描周期最多发起 4 次新派发尝试；节点总领取池并发 4、待处理与在途总数 128、每应用在途领取最多 1，按应用及队列轮转，同能力空探测合并一个周期。读空闲期限 60 秒、写期限 5 秒、单个数据库控制操作期限 8 秒。慢消费者导致连接关闭时，已提交状态仍由稳定身份恢复。

-这些是有界的开发基线，不代表经过容量压测的生产参数。当前同队列操作使用较粗的行锁协调，吞吐与公平性需要 P6 按负载验证。服务退出会显式关闭被 HTTP Upgrade 接管的连接；断开不会直接撤销外部已发出的请求。
+这些是有界的开发基线，不代表经过容量压测的生产参数。当前同队列操作使用较粗的行锁协调，节点内公平领取已实现；吞吐、多节点连接分布和应用延迟隔离需要 P6 按负载验证。服务退出会显式关闭被 HTTP Upgrade 接管的连接；断开不会直接撤销外部已发出的请求。

 协议 Schema 和真实进程强杀恢复已通过回归，见 [P2 阶段验收](../reports/phase-2.md)。[运行中取消](cancellation.md) 已实现并通过回归；凭据轮换、数据库故障切换、跨主机演练与容量验收属于后续生产验证。自动运行器对非协作处理器提供有界退出与状态报告，不能强制停止其外部副作用。
--- a/docs/examples/README.md
+++ b/docs/examples/README.md
@@ -92,6 +92,8 @@

 ## 计划场景与验收标准

+已可运行的 [优先级场景](../api/priority-and-fairness.md#4-sdk-完整场景) 提供 [完整源码](../../sdk/go/examples/priority/main.go)：按 0、9、4 受理后，以单槽 Worker 按 9、4、0 完成近同时到期的任务。前置为当前迁移/服务与队列、任务及 Worker 权限；预期 completed=3、attempts_per_task=1、worker_drained=true。无外部业务副作用，历史保留，失败非零退出，任务自带总时限；长等待补偿和其他应用隔离由真实数据库回归验证。
+
 已可运行的 [跨队列资源互斥场景](../api/keyed-concurrency.md#5-完整可运行场景) 提供 [完整源码](../../sdk/go/examples/keyed-concurrency/main.go)：两个队列的自动 Worker 操作同一资源，核对递增序号，并模拟资源端拒绝旧写入。输入使用显式 concurrency_key；预期 completed=2、resource_writes=2、stale_write_rejected=true。示例仅使用受控内存资源，无外部副作用；正常排空、保留历史，任务自带总时限。内存 mutex 不是生产分布式存储，生产必须在资源端原子持久化序号、操作身份和实际更新。

 | 场景 | 输入与步骤 | 预期结果 | 必测异常 | 状态 |
--- a/docs/reports/phase-3-priority-fairness.md
+++ b/docs/reports/phase-3-priority-fairness.md
@@ -0,0 +1,91 @@
+# P3 优先级与节点公平派发回归
+
+验证日期：2026-09-17。完成 [任务优先级、等待补偿、节点应用/队列轮转及 SDK 场景](../api/priority-and-fairness.md)。P3 可靠订阅、P4–P5 Weave、P6 生产负载/故障验收和 P7 最终交付核对仍未完成，持续目标保持进行中。
+
+## 1. 交付内容
+
+- POST /v1/tasks、查询/分页、计划模板、Worker 派发及独立 Go SDK 接入 Priority。值为 0–9，默认 0，随受理冻结、随安全重试保留。
+- [000012 迁移](../../internal/storage/mysql/migrations/000012_dispatch_priority.up.sql) 新增只读生成字段 DispatchAt 和排序索引，对既有 priority 增加范围 CHECK 和中文 COMMENT；生成时间等于 available_at 减 priority × 30 秒。真正的就绪时间、截止、权限、能力、门控和许可条件保持生效。
+- 以最多 270 秒的排序优势实现优先级加速；等待超过此优势的旧任务不被不断到来的最高级新任务持续插队。没有承诺 270 秒内完成或严格 FIFO。
+- [节点领取池](../../internal/dispatch/pool.go) 将原来的各连接并发轮询改为应用 → 队列 → 连接请求轮转。总并发 4、单应用在途 1、待处理加在途最多 128；每连接最多一个未完成请求。应用归属由认证后的数据库关系取得，不能按自报应用或不同命名空间分组。
+- 同命名空间/队列/精确能力的空探测在节点内合并一个周期，缓存最多 128 项；控制收发继续运行。所有任务状态、许可、预算和执行授权仍由数据库事务决定。
+- [可运行示例](../../sdk/go/examples/priority/main.go)、协议 Schema、接口与 SDK 文档同步更新。当前仍为 33 个实体，274 个直接声明持久化字段全部有中文注释，最终数据库外键为零。
+
+## 2. 环境和执行
+
+macOS 本机、Go 1.27.1、Docker MySQL 8.4.10、回环 HTTP/WSS 和一次性数据库。测试使用随机私密凭据，结束清理自建容器，不连接既有业务库。
+
+```sh
+make fmt test vet build
+make integration
+cd sdk/go
+GOWORK=off go test -race ./...
+```
+
+上述检查通过。真实数据库、SDK、示例和进程故障来自 scripts/test-mysql.sh；普通未配置环境的 go test 会跳过这些外部用例，不能替代完整集成。
+
+| 分组 | 本次结果 |
+| --- | --- |
+| 全部 MySQL 集成 | PASS，74.570 秒 |
+| 优先级四组数据库场景 | PASS，0.56 秒 |
+| 公平领取应用隔离 | PASS，1.43 秒 |
+| SDK Worker 连接、运行器、重试、取消、优先级与断线 | PASS，88.849 秒 |
+| SDK 优先级输入与执行顺序 | PASS，3.16 秒 |
+| SDK 计划生命周期 | PASS，5.659 秒（含包开销） |
+| SDK 队列 / 应用资源 | PASS，4.470 / 1.416 秒（含包开销） |
+| 七项真实进程故障组 | PASS，28.296 秒 |
+| 其中优先级强杀恢复 | PASS，3.14 秒 |
+| 十二个完整 SDK 示例 | 全部通过 |
+
+十二个示例：health、tasks、worker-protocol、worker、history、retry、schedules、cancellation、resources、keyed-concurrency、priority、application-resources。回归耗时不代表吞吐、延迟 SLO 或生产容量。
+
+## 3. 优先级与数据库证据
+
+[优先级数据库用例](../../internal/storage/mysql/priority_integration_test.go) 验证：
+
+1. 9 级任务先于 5 秒前到期的 0 级任务领取；尚有一小时才到期的 9 级任务不被提前领取。详情、摘要及派发保留 priority。
+2. 0 级任务已等待 271 秒时，即使候选前缀有 24 条新 9 级任务，也先取得原任务，避免候选数量截断造成的饥饿。
+3. 明确失败进入退避后保留 9 级，数据库生成字段与 available_at 差 270 秒；退避前不领取，到期后第二次尝试正常成功。
+4. 默认 0 的原键原内容继续取回原回执；同键改优先级冲突；负数和 10 被拒绝。直接写入超范围 priority 和独立修改 generated 字段均由数据库拒绝。
+
+[计划及资源键集成](../../internal/storage/mysql/keyed_concurrency_integration_test.go) 同时验证不可变计划模板传递 Priority=7、资源键和递增许可序号；资源互斥不被优先级绕过。
+
+升级回归继续验证 v4 安全策略、v9 应用配额及旧在途任务释放。v7 升级保留全部 325 个原有索引列定义，移除 70 个外键，既有任务内容不变；新增生成列对旧默认 0 任务等于原 available_at，新排序索引单独添加。模型/表列映射与完整零外键检查同步通过。
+
+## 4. 公平领取与资源隔离证据
+
+[领取池竞态用例](../../internal/dispatch/pool_test.go) 验证：
+
+- 同应用 40 个繁忙队列连接请求，不能挤掉该应用另一个队列以及另一个应用的轮次。
+- 全局在途数与单应用在途数不超上限；等待和执行中的请求共同受总容量约束，满额拒绝追加，不能把请求无限移入内部切片。
+- 一个应用阻塞时其他应用仍进入领取；取消的待处理请求不执行、不占用后续轮次，释放容量并移除空组。
+- 并发提交和关闭竞争时不再接新工作，取消在途操作，最终没有领取槽泄漏。
+
+[空探测用例](../../internal/transport/httpserver/worker_dispatch_test.go) 验证 20 次同能力空探测只调用一次存储；能力集合顺序不影响身份，不同资源键支持声明分别探测；过期后再次访问数据库，缓存不超过 128 项，领取 panic 被隔离且不暴露原始异常。
+
+[真实 MySQL/WSS 用例](../../internal/storage/mysql/fair_dispatch_integration_test.go) 使用一个节点、两个应用、13 条 Worker 连接以及仅 4 条连接的数据库池。显式持有繁忙应用的额度行锁，启用该应用 12 条消费连接，并通过 performance_schema.data_lock_waits 确认真实领取事务已经等待。保持锁未释放时，另一个应用成功更新容量并收到自身任务的持久化派发。随后才释放故障锁。
+
+这个用例证明节点领取池不会因一个应用的多条连接等待额度而耗尽全部数据库连接。它没有把“领取隔离”扩大为所有管理/续租请求的资源隔离，也没有宣称跨节点完全相等吞吐或为新应用保留连接席位。
+
+## 5. SDK 与进程恢复
+
+[SDK 集成用例](../../sdk/go/priority_integration_test.go) 通过真实 HTTP 拒绝 -1、10、非整数、null、字符串和 bool；按 0、9、4 受理后，单槽自动 Worker 按 9、4、0 完成，任务查询和处理器看到相同冻结值。
+
+进程用例在节点 A 保存三条不同优先级任务后强杀并 Wait 确认退出，启动不同 node_id 的 B，再接入 Worker。B 按 9、4、0 从数据库恢复领取，逐条 Start/Finish 成功，排序不依赖 A 的内存。
+
+完整示例实际输出：
+
+```text
+submitted_priorities=0,9,4 executed_priorities=9,4,0
+completed=3 attempts_per_task=1 worker_drained=true
+```
+
+原 Start/Finish ACK 丢失、Worker 强杀未知核查、计划强杀补跑、跨队列资源键恢复和应用额度持久化故障用例均在本次完整套件中通过。异步领取未使这些既有执行不变量失效。
+
+## 6. 仍需验证的边界
+
+- 调度池是节点内领取机会轮转。跨节点配额仍依赖共享 MySQL；连接分布不均时没有严格相同全局份额或全局权重。
+- 每节点仍只接受 128 条 Worker 连接，没有每应用席位预留；请求级限流、恶意连接占用和全套资源隔离需要生产接入治理。
+- 优先级不抢占已有执行，未来任务不会提前执行。暂停、额度不足、资源键占用、无兼容 Worker、旧积压和长任务都可能延长等待；排序优势不是时限承诺。
+- 同能力空探测最多增加一个扫描周期的发现等待；满额、失去权限、节点重启或缓存丢失均不能授权执行。内存队列被丢弃后由重新扫描及持久化租约恢复。
+- 生产还需验证 MySQL 索引选择、未来任务和高基数能力下的扫描成本、锁等待、混合负载公平性、队列/应用热点、数据库故障切换、RPO/RTO 和容量余量。迁移生成列和建索引需要目标规模维护窗口演练。
--- a/docs/sdk/README.md
+++ b/docs/sdk/README.md
@@ -179,4 +179,4 @@ task=<任务ID> state=SUCCEEDED attempts=1 evidence=1 reason=RESULT_CONFLICT dis

 ## 7. 后续交付

-P2 已提供底层协议、[自动 Worker 运行器及示例](worker-runtime.md) 与历史查询，并通过 [Schema 及进程故障阶段验收](../reports/phase-2.md)；P3 已实现 [安全重试](../api/retries.md)、[计划调度](../api/schedules.md)、[运行中取消](../api/cancellation.md) 、[队列资源控制及示例](../api/queues.md) 和 [应用共享配额及示例](../api/application-resources.md)，[资源键互斥和单调序号示例](../api/keyed-concurrency.md) 已实现，优先级/公平性和结果订阅继续开发；P4–P5 提供流程构建发布、信号、等待、轮询与人工恢复。每项随实现同步交付可运行示例及异常回归。
+P2 已提供底层协议、[自动 Worker 运行器及示例](worker-runtime.md) 与历史查询，并通过 [Schema 及进程故障阶段验收](../reports/phase-2.md)；P3 已实现 [安全重试](../api/retries.md)、[计划调度](../api/schedules.md)、[运行中取消](../api/cancellation.md) 、[队列资源控制及示例](../api/queues.md) 和 [应用共享配额及示例](../api/application-resources.md)，[资源键互斥和单调序号示例](../api/keyed-concurrency.md) 已实现，[优先级场景和节点公平派发](../api/priority-and-fairness.md) 已实现，结果订阅继续开发；P4–P5 提供流程构建发布、信号、等待、轮询与人工恢复。每项随实现同步交付可运行示例及异常回归。