feat: add automatic Worker runtime with lease recovery and bounded shutdown

2026-09-17 14:29:28 +08:00
parent 1753fcbccb
commit da123bba69
22 changed files with 1784 additions and 17 deletions
--- a/README.md
+++ b/README.md
@@ -8,9 +8,9 @@ Orbit 是面向多个业务项目的通用任务调度与流程编排平台，
 ## 当前进度
-已实现 32 个数据模型、版本化迁移、凭据及范围校验、队列创建查询、任务幂等提交/查询/分页/待执行取消，以及对应 Go SDK 和示例。P2 服务端执行内核、WSS 和独立 Worker 底层 SDK 已通过阶段内回归，可实际完成文本处理任务；自动 Worker 运行器、调度器和流程引擎按 [持续开发计划](docs/08-development-plan.md) 继续实现。
+已实现 32 个数据模型、版本化迁移、凭据及范围校验、队列创建查询、任务幂等提交/查询/分页/待执行取消，以及对应 Go SDK 和示例。P2 服务端、WSS、底层 SDK 与自动 Worker 运行器已通过阶段内回归，支持自动心跳/续租/重连及有界排空；查询补全、调度器和流程引擎按 [持续开发计划](docs/08-development-plan.md) 继续实现。
-readiness 只表示数据库与迁移记录可用，不表示完整平台已具备生产服务能力。验证证据见 [P0](docs/reports/phase-0.md)、[P1](docs/reports/phase-1.md)、[P2 服务端记录](docs/reports/phase-2-server.md) 与 [P2 SDK 协议记录](docs/reports/phase-2-sdk-protocol.md)。
+readiness 只表示数据库与迁移记录可用，不表示完整平台已具备生产服务能力。验证证据见 [P0](docs/reports/phase-0.md)、[P1](docs/reports/phase-1.md)、[P2 服务端记录](docs/reports/phase-2-server.md)、[P2 SDK 协议记录](docs/reports/phase-2-sdk-protocol.md) 与 [自动运行器记录](docs/reports/phase-2-worker-runtime.md)。
 ## 目录
@@ -53,7 +53,7 @@ cd sdk/go
 ORBIT_URL=http://127.0.0.1:8080 go run ./examples/health
 ```
-任务接入从 [初始化凭据](docs/api/authentication.md) 开始，再按 [SDK 接入](docs/sdk/README.md) 运行受理/取消示例。另有 [Worker 协议示例](docs/sdk/worker.md)，实际领取并处理文本、提交结果与排空；自动运行器仍在开发。
+任务接入从 [初始化凭据](docs/api/authentication.md) 开始，再按 [SDK 接入](docs/sdk/README.md) 运行受理/取消示例。[自动 Worker 示例](docs/sdk/worker-runtime.md) 演示处理器注册、并发消费、结果确认与排空；特殊接入也可使用 [底层协议示例](docs/sdk/worker.md)。
 ## 开发与回归
--- a/docs/08-development-plan.md
+++ b/docs/08-development-plan.md
@@ -26,7 +26,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 底层协议及实际 ACK 丢失恢复回归通过；文本执行示例可运行；自动运行/重连/退出、查询与完整验收待完成 |
+| P2 Worker 执行闭环 | WSS 接入、能力/容量、领取与开始、租约、续租、结果确认、排空与恢复；Worker SDK | 真 Worker 执行；失联/重连/重复确认/旧尝试拒绝；业务效果未知转核查；节点故障接管 | 开发中：服务端、SDK 协议和自动运行器通过阶段内回归；跨初始租约执行、自动重连/证据重报、有界退出及并发验证通过；尝试/证据查询、完整 Schema 和阶段验收待完成 |
 | P3 Pulse 完整能力 | 安全重试、延时、Cron/固定间隔、漏跑策略、计划版本、并发许可、配额/背压、可靠结果订阅 | 多实例领取/触发竞争、重试上限、取消竞争、队列隔离、积压恢复、事件重复交付 | 待开发 |
 | P4 Weave 主流程 | SDK 定义构建与发布校验、实例、顺序/分支/结构化并行汇合、信号/定时等待、版本绑定 | 重启接续、早到/重复信号、并行竞争、内部事件重放、发布版本兼容；端到端通用流程 | 待开发 |
 | P5 Weave 恢复与查询 | 有界查询、暂停继续、取消、人工核查恢复、控制门控与审计 | 轮次与尝试独立预算；暂停/开始/回执/超时竞争；恢复保留预算；未知结果不盲目重复 | 待开发 |
@@ -75,3 +75,4 @@ SDK、文档与示例随 P1–P5 同步开发，P7 是全量核对，不是最
 - [P1 验证记录](reports/phase-1.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/P1 已完成，P2 服务端与 Worker 底层 SDK 已通过阶段内回归，自动 Worker 运行器继续开发；尚未完成生产验收
+- 阶段：P0/P1 已完成，P2 服务端、底层 SDK 与自动 Worker 运行器已通过阶段内回归，查询/协议验收继续推进；尚未完成生产验收
 - 适用范围：Orbit 统一平台，包含 Pulse 任务调度模块、Weave 流程编排模块与公共能力。平台面向多个业务系统复用。
 ## 阅读顺序
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -11,7 +11,7 @@
 | `/v1/tasks` 提交、查询、分页与待执行取消 | P1 已实现 | [任务接口](tasks.md) |
 | `/v1/queues` 创建与查询 | P1 已实现 | [队列接口](queues.md) |
 | 凭据校验与初始化 CLI | P1 已实现 | [鉴权](authentication.md) |
-| `/v1/worker/connect` | P2 服务端及底层 SDK 已实现，自动 Worker 运行器开发中 | [Worker 契约](worker.md) |
+| `/v1/worker/connect` | P2 服务端、底层 SDK 与自动 Worker 已实现；完整阶段验收继续推进 | [Worker 契约](worker.md) |
 | `/v1/schedules` 与计划管理 | 计划 P3，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
 | `/v1/events/connect` | 计划 P3，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
 | `/v1/workflows` 与流程管理 | 计划 P4–P5，尚未实现 | [流程接口规划](workflows.md) |
--- a/docs/api/worker.md
+++ b/docs/api/worker.md
@@ -1,6 +1,6 @@
 # Worker 通信与执行契约 v1（开发中）
-已实现服务端执行事务、WebSocket 接入、[独立 Go 底层协议 SDK](../sdk/worker.md) 及真实 WSS/ACK 丢失回归。**P2 尚未完成**：自动 Worker 运行器、自动重连/续租、处理器生命周期与优雅退出还在开发。本页记录当前可验证的协议；底层 SDK 不自动管理处理器。
+已实现服务端执行事务、WebSocket 接入、[独立 Go 底层协议 SDK](../sdk/worker.md) 和 [自动 Worker 运行器](../sdk/worker-runtime.md)，通过真实 WSS、自动续租、ACK 丢失/持续断网恢复及有界退出回归。**P2 尚未完成**：尝试/证据查询、完整协议 Schema 与完整阶段验收继续推进。底层 WorkerConnection 不自动管理处理器；NewWorker / Run 提供自动管理。
 ## 1. 接入与身份
@@ -143,4 +143,4 @@ receipt 是原操作的不可变确认；lease 是本次重新核验的执行权
 这些是有界的开发基线，不代表经过容量压测的生产参数。当前同队列操作使用较粗的行锁协调，吞吐与公平性需要 P6 按负载验证。服务退出会显式关闭被 HTTP Upgrade 接管的连接；断开不会直接撤销外部已发出的请求。
-运行中取消、SDK 自动重连/续租、非协作处理器处理、完整 WS JSON Schema、凭据轮换和多节点进程级故障演练尚未全部完成。实际证据见 [P2 服务端阶段记录](../reports/phase-2-server.md)。
+运行中取消、完整 WS JSON Schema、凭据轮换和多节点进程级故障演练尚未全部完成。SDK 已实现自动重连/续租、非协作处理器的有界退出与状态报告；实际证据见 [P2 服务端阶段记录](../reports/phase-2-server.md) 和 [自动运行器回归](../reports/phase-2-worker-runtime.md)。
--- a/docs/examples/README.md
+++ b/docs/examples/README.md
@@ -25,9 +25,17 @@
 - 前置：专用 Worker 凭据，启动步骤见 [Worker SDK 文档](../sdk/worker.md)。
 - 输入与步骤：提交 `{"text":"  Hello Orbit  "}` → 注册/容量 → 领取 → 开始授权 → 实际处理 → 确认结果 → 查询 → 排空。
 - 预期：SUCCEEDED、一次尝试、结果 `{"text":"HELLO ORBIT"}`。
- 异常：控制 ACK 丢失使用原身份有限重报；业务函数不随重连再次调用；迟到证据不能当作成功结果。自动续租与持续消费仍待运行器实现。
+- 异常：底层示例使用原身份有限重报控制 ACK；业务函数不随重连再次调用；迟到证据不能当作成功结果。自动续租与持续消费见下方运行器示例。
 - 清理：任务历史保留；运行结束确认排空并关闭连接。每次示例使用独立任务/处理器身份。
 ## 已可运行：自动 Worker 并发消费
 - 源码：[自动 Worker 示例](../../sdk/go/examples/worker/main.go)，[接入与启动命令](../sdk/worker-runtime.md)。
 - 步骤：注册版本化处理器 → Run → 以容量 2 消费三条文本任务 → 查询结果 → 取消 Run context 并等待排空。
 - 预期：三条规范化结果、started=3、confirmed=3、running=0；输入与结果均由实际代码处理。
 - 异常：自动心跳/续租与原身份重连；普通错误/panic 按未知效果报告，超时退出不声称杀死 goroutine；完整故障证据见 [回归记录](../reports/phase-2-worker-runtime.md)。
 - 清理：正常排空关闭连接，保留历史；进程被强杀后的在途状态由租约恢复与核查衔接。
 ## 计划场景与验收标准
 | 场景 | 输入与步骤 | 预期结果 | 必测异常 | 状态 |
--- a/docs/reports/phase-2-sdk-protocol.md
+++ b/docs/reports/phase-2-sdk-protocol.md
@@ -1,6 +1,6 @@
 # P2 Worker SDK 协议阶段回归
-日期：2026-09-17。此记录覆盖独立 SDK 的底层连接和一次性执行闭环，**不代表 P2 完成，也不代表自动 Worker 运行器已交付**。
+日期：2026-09-17。此历史阶段记录覆盖独立 SDK 的底层连接和一次性执行闭环，**不代表 P2 完成，也不覆盖自动 Worker 运行器**。后续运行器的实现与验证见 [独立报告](phase-2-worker-runtime.md)。
 ## 实现范围
--- a/docs/reports/phase-2-worker-runtime.md
+++ b/docs/reports/phase-2-worker-runtime.md
@@ -0,0 +1,50 @@
 # P2 自动 Worker 运行器回归
 日期：2026-09-17。自动运行器已实现并通过本轮回归；P2 仍需补齐尝试/证据查询、协议 Schema 及完整阶段验收。没有修改已有迁移或持久化模型。
 ## 本轮实现
 独立 SDK 新增 NewWorker / Run / Stats / Events，支持能力注册、容量限制、独立处理器执行、自动会话心跳、自动任务续租、稳定身份重连、结果重报及有界排空。业务明确失败与未知效果分开；panic、Goexit 和不可接受的结果都有稳定分类。配置及数据结构提供中文注释。
 网络控制和处理器执行分离；租约监视器独立工作，不能因控制请求阻塞而延长权限。过期取消不可逆，新的较短会话期限也会缩短本地授权。当前控制请求按连接串行，吞吐取决于数据库/网络与配置容量，需要 P6 负载验证。
 ## 验证环境与入口
 macOS arm64、Go 1.27.1、Docker MySQL 8.4.10、锁定 coder/websocket v1.8.15。真实 Orbit 命令运行在随机回环端口，SDK WSS 故障网关使用受信任测试证书，不跳过 TLS 验证。
 ```sh
 make test
 make vet
 make build
 make integration
 cd sdk/go
 GOWORK=off go test -race ./...
 GOWORK=off go vet ./...
 ```
 隔离集成脚本先运行既有模型/迁移/任务/Worker/WSS 回归，再启动真实服务器与 Worker 专用凭据，执行底层 SDK 和自动运行器测试及全部示例。凭据不进入 URL、命令行参数或输出，结束后移除隔离测试容器。
 ## 通过的场景
 | 场景 | 实际断言 |
 | --- | --- |
 | 自动重连与双重 ACK 丢失 | 网关分别在实际服务提交 start / finish 后丢 ACK；运行器自动重连核对，处理器只调用一次，服务端仅一次尝试，结果保持精确数值 |
 | 跨越初始租约的执行 | 处理器执行 32 秒，跨越服务端首次 30 秒租约，至少两次自动续租确认后仍取得权威 SUCCEEDED |
 | 收尾期间保持执行 | 处理器开始后立即取消 Run context，运行器持久化排空并在 45 秒 grace 内继续续租/收集结果，正常返回且 Running=0 |
 | 业务失败与未知效果 | 明确 WorkerFailure → FAILED；普通 error 和 panic → NEEDS_REVIEW；SDK 不泄露异常正文 |
 | 不协作的处理器 | 函数忽略 context 时，250 毫秒收尾期限后 Run 有界返回，错误记录 1 个未确认尝试和仍运行的处理器，没有声称杀死 goroutine |
 | 自动租约到期取消 | 达到单次尝试时限后处理器观察到 ErrExecutionLeaseLost，只调用一次，任务进入 NEEDS_REVIEW |
 | 持续断网与证据重报 | 断开活跃 WSS 并让网关拒绝重连，处理器仍按本地期限取消；恢复服务后自动上报待确认结果，收到 EVIDENCE_ONLY，权威状态和尝试数不变 |
 | 实际业务并发上限 | 6 个任务、容量 2，处理器实际峰值恰为 2，所有任务一次尝试完成并排空 |
 | 租约监视器 | 续期后旧期限不取消处理器；新会话缩短期限被采用；到期后更新不能复活 |
 | 卡住的握手与认证失败 | HTTP 握手不返回时，50 毫秒 grace 仍能中断并收尾；HTTP 401 立即终止且不执行处理器，不输出上游原始正文 |
 | 处理器异常保护 | panic、runtime.Goexit、重复 JSON 键、超范围数字与超深结果均产生受控 UNKNOWN 报告；执行计数正确释放 |
 | 实际命令行示例 | 自动 Worker 执行三条文本规范化任务；started=3、confirmed=3、running=0，结果按预期转换 |
 以上为正确性和受控故障证据，不是性能基准。实际自动恢复测试运行在同一真实服务进程后面的 WSS 故障网关；已有服务端测试覆盖不同 node ID 的租约迁移，但本轮未把这两层合并描述成 SDK 多主机宕机验收。
 ## 限制与下一步
 未确认结果只在 Worker 进程内保留，强杀进程后由服务端租约恢复与业务核查衔接。业务副作用幂等、资源端代次隔离、宿主机/数据库故障与部署拓扑仍需对应验证。运行器不提供业务自动重试；策略性重试在 P3。
 继续补齐 P2 尝试/证据查询和协议 Schema；再进入 P3 的重试、计划、配额、可靠事件订阅。不会以本轮 SDK 回归代替全平台生产验收。
--- a/docs/sdk/README.md
+++ b/docs/sdk/README.md
@@ -1,6 +1,6 @@
 # Go SDK 接入说明
-已实现健康查询、任务提交/查询/分页/待执行取消、队列创建/查询，以及 [Worker 底层协议 SDK](worker.md)。自动 Worker 运行器和流程构建接口按 [开发计划](../08-development-plan.md) 继续实现。
+已实现健康查询、任务提交/查询/分页/待执行取消、队列创建/查询、[自动 Worker](worker-runtime.md) 和 [Worker 底层协议 SDK](worker.md)。流程构建等后续接口按 [开发计划](../08-development-plan.md) 继续实现。
 module：`git.yuntuo.hk/k2safe/orbit/sdk/go`。SDK 使用独立 go.mod，依赖 Go 标准库与 `github.com/coder/websocket v1.8.15`，不引用服务端模型或数据库实现。
@@ -133,4 +133,4 @@ go mod tidy
 ## 6. 后续交付
-P2 已提供 Worker 底层注册、WSS、能力/容量、执行确认、续租、恢复和排空接口及 [可运行示例](worker.md)，继续开发自动 Worker 运行器；P3 提供计划与结果订阅；P4–P5 提供流程构建发布、信号、等待、轮询与人工恢复。每项随实现同步交付可运行示例及异常回归。
+P2 已提供底层协议与 [自动 Worker 运行器及示例](worker-runtime.md)，继续补齐查询与阶段验收；P3 提供计划与结果订阅；P4–P5 提供流程构建发布、信号、等待、轮询与人工恢复。每项随实现同步交付可运行示例及异常回归。
--- a/docs/sdk/worker-runtime.md
+++ b/docs/sdk/worker-runtime.md
@@ -0,0 +1,109 @@
 # 自动 Worker 接入
 更新：2026-09-17。自动 Worker 已实现，并通过真实 MySQL、实际服务命令、WSS 断线/ACK 丢失/持续断网回归。P2 的尝试与证据查询、完整协议 Schema 和进程级故障验收仍需继续完成。
 源码：[运行器](../../sdk/go/worker_runtime.go)、[配置与中文注释](../../sdk/go/worker_runtime_types.go)、[完整示例](../../sdk/go/examples/worker/main.go)。特殊传输集成可以使用 [底层协议 SDK](worker.md)，普通消费直接使用本页的 Worker。
 ## 1. 运行完整示例
 按 [底层 SDK 的初始化步骤](worker.md#1-可运行的文本规范化示例) 创建具有 Worker 权限的专用凭据，在仓库根目录执行：
 ```sh
 cd sdk/go
 ORBIT_URL=http://127.0.0.1:8080 \
  ORBIT_CREDENTIALS_FILE=../../.local/worker.credentials.json \
  go run ./examples/worker
 ```
 示例提交三条文本任务，以容量 2 启动自动 Worker，真实执行文本规范化，查询结果后取消 Run context 并等待排空。预期输出：
 ```text
 task=<任务ID> state=SUCCEEDED result={"text":"HELLO ORBIT"}
 task=<任务ID> state=SUCCEEDED result={"text":"REUSABLE WORKER"}
 task=<任务ID> state=SUCCEEDED result={"text":"DURABLE RESULT"}
 worker_drained=true started=3 confirmed=3 running=0
 ```
 每次示例使用独立操作和能力名称，避免接走以前运行留下的任务；任务与审计历史保留。生产通常使用固定处理器版本，由独立长驻 Worker 消费；本示例把生产者和消费者放在一个命令里方便复现。
 ## 2. 注册处理器与启动
 以下为接入函数片段；函数收到的 ctx 应来自进程信号或应用生命周期，并等待 Run 返回后再退出进程。
 ```go
 worker, err := orbit.NewWorker(client, orbit.WorkerOptions{
    QueueID: queueID,
    Capacity: 4,
    ShutdownTimeout: 30 * time.Second,
    Handlers: []orbit.WorkerHandler{{
        Capability: orbit.WorkerCapability{
            Handler: "text.normalize", HandlerVersion: "v1", PayloadVersion: "v1",
        },
        Handle: func(ctx context.Context, execution orbit.WorkerExecution) (json.RawMessage, error) {
            // 实际 HTTP/数据库/文件操作应使用这个 ctx，并实现业务效果幂等。
            if err := ctx.Err(); err != nil { return nil, err }
            return json.RawMessage(`{"processed":true}`), nil
        },
    }},
 })
 if err != nil { return err }
 return worker.Run(ctx)
 ```
 任务的 handler、handler_version、payload_version 必须和注册能力精确匹配。处理器收到 Task、AttemptID 与执行 Epoch，不收到实例/尝试秘密。Task.ID 或接入方保存的业务操作键用于效果去重；AttemptID 标识一次尝试，不能作为跨尝试的业务幂等键。资源侧支持执行代次校验时，可拒绝旧 Epoch 的写入。
 SDK 的 Run 每个实例只能调用一次，包括已经正常退出的实例。重连由内部保留原身份处理；不要通过反复 NewWorker 来代替断线恢复。进程重启会生成新身份，不能继续使用旧进程的内存状态来声称已经完成。
 ## 3. 配置和接口
 | 配置 | 默认 / 范围 | 含义 |
 | --- | --- | --- |
 | QueueID | 必填，32 位 ID | 当前凭据有消费权限的队列 |
 | Capacity | 4；1–256 | 同时尚未返回的处理器上限；不响应取消的函数仍占物理槽 |
 | Handlers | 1–32 项 | 精确能力，重复能力和空函数在构造时拒绝 |
 | ShutdownTimeout | 30 秒；1 毫秒–5 分钟 | 从 Run context 取消起计算的整体收尾期限 |
 | ReconnectMinDelay | 200 毫秒；至少 10 毫秒 | 连接失败退避起点 |
 | ReconnectMaxDelay | 5 秒；不小于起点，最多 30 秒 | 指数退避上限，区间抖动；不增加任务尝试次数 |
 `Run(ctx)` 正常排空返回 nil；同实例再次运行返回 ErrWorkerAlreadyRun。`Stats()` 返回进程内 Running、Started、RenewalsConfirmed、ReportsConfirmed、EvidenceConfirmed、Reconnects、DroppedEvents 快照，不是持久化业务成功率。
 `Events()` 是 128 条缓冲的只读本地通知流，不读取也不会阻塞运行；缓冲满时丢弃并计数，Run 返回时关闭。通知只含类型、任务/尝试 ID 与稳定分类，没有业务结果或秘密。它不能代替审计、可靠结果订阅或任务查询。
 ## 4. 执行、续租与恢复
 - 只有 Start 当前授权有效才调用处理器；同进程中的已知尝试最多调用一次。重复确认与重新连接只核对控制操作。
 - 处理器在独立 goroutine 执行，网络控制由事件循环管理；每连接当前只保留一个执行器控制请求在途。不同处理器可以并行，控制请求顺序与业务并发上限分开。
 - 会话心跳按服务端 TTL 的三分之一计算，上限 5 秒。任务续租按当前保守租约剩余时间的三分之一安排，下限 20 毫秒；服务器仍限制总截止与单次尝试时限。
 - 每个处理器的租约监视器独立取消 context，断网或控制请求阻塞也不会延长本地执行权限。最新会话若缩短租约，监视器会采用较短期限。已到期的处理器不会被后续确认复活。
 - 重连复用实例和尝试身份，在开启容量之前 Resume 所有已知尝试；待确认 start/renew/finish 使用原消息 ID。认证、权限及协议错误终止 Run；临时服务/连接错误按退避核对。
 - 结果未确认或处理器失去租约时，运行器降低对外声明的容量。仍未返回的函数占用真实并发槽；已在传输中的预占会有界接收，已知尝试最多为配置容量的两倍。
 Run 的重连是控制消息恢复，不是业务自动重试。当前明确失败仍成为 FAILED；策略化业务重试在 P3 实现。
 ## 5. 结果与错误分类
 | 处理器结果 | SDK 报告 / 服务端行为 |
 | --- | --- |
 | 合法非 null JSON + nil error | SUCCEEDED |
 | `&orbit.WorkerFailure{Code:"OBJECT_REJECTED", Details:...}` | FAILED；仅用于能确认的业务失败，Details 为空时为 `{}` |
 | 普通 error | UNKNOWN / HANDLER_ERROR，进入 NEEDS_REVIEW |
 | panic / runtime.Goexit | UNKNOWN / HANDLER_PANIC 或 HANDLER_ABORTED |
 | 非法 JSON、超限结果、不支持数值或嵌套 | UNKNOWN / INVALID_HANDLER_RESULT |
 | 处理器因租约取消返回错误 | UNKNOWN / LEASE_LOST |
 | 报告到达时租约已失效、或结果与权威状态冲突 | 服务端可只保存 EVIDENCE_ONLY；不把证据计为任务成功 |
 原始异常和 panic 内容不写入结果或通知。Result/Details 最多 256 KiB，应优先使用对象引用。SDK 保留精确数字文本，并按服务端数字范围及完整帧的嵌套上限预检，避免产生永远无法接受的报告。
 普通网络错误不能证明副作用未发生，因此不会自动解释为明确失败。UNKNOWN 和迟到证据的后续核查由平台管理能力与业务对账共同处理。
 ## 6. 退出与故障边界
 取消 Run context 后，运行器请求持久化排空，收集排空 ACK 之前已派发的工作，继续为在途任务续租并确认结果。进程应等待 Run 返回，而不是取消 context 后立即退出。
 ShutdownTimeout 从取消信号发生时开始计时，包含网络等待和处理器收尾。到期后取消控制请求及处理器 context，返回 `*WorkerRunError`；可用 `errors.Is(err, orbit.ErrWorkerShutdownTimeout)` 判断，Unconfirmed 和 Running 给出终止收尾时的快照。其他致命错误也带这些计数，便于识别未核对的执行。
 Go 无法杀死忽略 context 的 goroutine。Run 可以有界返回，但这类函数可能仍在进程中执行；不得把返回错误解释为副作用已停止，也不要在同一进程盲目重建 Worker 叠加执行。服务端对失联执行按租约回收并进入核查。
 身份、尚未确认的结果和消息 ID 当前保存在内存，支持同进程重连；进程被强杀会失去这些内容。持久化租约、操作回执、最终结果和审计在 MySQL 中，业务外部效果仍需要业务幂等或查询核对。这一边界不等于端到端 exactly-once。
 本轮证据见 [自动运行器回归报告](../reports/phase-2-worker-runtime.md)。实际部署中的多主机故障、数据库复制确认与容量承诺仍需后续生产验收。
--- a/docs/sdk/worker.md
+++ b/docs/sdk/worker.md
@@ -1,6 +1,6 @@
 # Go Worker 底层协议 SDK
-更新：2026-09-17。已实现可独立构建的 `WorkerConnection`，配合真实 Orbit 服务和 MySQL 通过控制操作、WSS、ACK 丢失与租约过期回归。**自动 Worker 运行器仍在开发**：本页的方法不会自动启动处理器、心跳、续租、重连或排空。需要持续消费的接入方应等待运行器交付，不能把一次性示例当作完整托管运行时。
+更新：2026-09-17。已实现可独立构建的 `WorkerConnection`，配合真实 Orbit 服务和 MySQL 通过控制操作、WSS、ACK 丢失与租约过期回归。本页是底层接口，不自动启动处理器、心跳、续租、重连或排空；普通持续消费使用已实现的 [自动 Worker 运行器](worker-runtime.md)。
 源码：[连接与控制方法](../../sdk/go/worker_connection.go)、[中文注释的数据契约](../../sdk/go/worker_types.go)。传输字段、权限和事务语义见 [Worker 接口](../api/worker.md)。SDK 独立 module，只依赖标准库和锁定版本的 `github.com/coder/websocket v1.8.15`，不导入服务端包。
--- a/scripts/test-mysql.sh
+++ b/scripts/test-mysql.sh
@@ -49,5 +49,6 @@ if [ -z "$TASK_HTTP_PORT" ]; then printf '%s\n' 'Bootstrap HTTP server did not s
 (cd sdk/go && ORBIT_URL="http://127.0.0.1:$TASK_HTTP_PORT" "$TASK_GO" run ./examples/health)
 (cd sdk/go && ORBIT_URL="http://127.0.0.1:$TASK_HTTP_PORT" ORBIT_CREDENTIALS_FILE="$TASK_TEST_DIR/sdk.credentials.json" "$TASK_GO" run ./examples/tasks)
 ORBIT_MYSQL_DSN="$ORBIT_TEST_MYSQL_DSN" "$TASK_TEST_DIR/orbit-admin" bootstrap --application sdk-worker --namespace default --environment test --queue worker-examples --worker-access --output "$TASK_TEST_DIR/worker.credentials.json"
-(cd sdk/go && ORBIT_TEST_WORKER_URL="http://127.0.0.1:$TASK_HTTP_PORT" ORBIT_TEST_WORKER_CREDENTIALS_FILE="$TASK_TEST_DIR/worker.credentials.json" "$TASK_GO" test -race -count=1 -run IntegrationWorkerConnection -v .)
+(cd sdk/go && ORBIT_TEST_WORKER_URL="http://127.0.0.1:$TASK_HTTP_PORT" ORBIT_TEST_WORKER_CREDENTIALS_FILE="$TASK_TEST_DIR/worker.credentials.json" "$TASK_GO" test -race -count=1 -run 'IntegrationWorker(Connection|Runtime)' -v .)
 (cd sdk/go && ORBIT_URL="http://127.0.0.1:$TASK_HTTP_PORT" ORBIT_CREDENTIALS_FILE="$TASK_TEST_DIR/worker.credentials.json" "$TASK_GO" run ./examples/worker-protocol)
 (cd sdk/go && ORBIT_URL="http://127.0.0.1:$TASK_HTTP_PORT" ORBIT_CREDENTIALS_FILE="$TASK_TEST_DIR/worker.credentials.json" "$TASK_GO" run ./examples/worker)
--- a/sdk/go/doc.go
+++ b/sdk/go/doc.go
@@ -1,4 +1,5 @@
 // Package orbit 是 Orbit 的独立 Go SDK，提供健康、任务、队列与 Worker 底层协议。
-// WorkerConnection 不自动重连、续租或运行处理器；自动运行器与流程 SDK 仍在开发。
+// WorkerConnection 是底层接口；NewWorker/Run 自动管理处理器、续租、恢复与排空。
 // 流程 SDK 等后续能力按阶段继续开发。
 // SDK 不导入服务端模型、迁移或数据库依赖。
 package orbit
--- a/sdk/go/examples/worker-protocol/main.go
+++ b/sdk/go/examples/worker-protocol/main.go
@@ -1,5 +1,5 @@
 // worker-protocol 演示一次文本规范化任务的真实执行与原消息重报。
-// 这是底层协议示例；持续运行、自动续租与优雅退出由后续 Worker 运行器提供。
+// 这是底层协议示例；持续运行、自动续租与优雅退出见 examples/worker 的运行器示例。
 package main
 import (
--- a/sdk/go/examples/worker/main.go
+++ b/sdk/go/examples/worker/main.go
@@ -0,0 +1,133 @@
 // worker 演示自动 Worker：声明处理器，Run 管理连接/心跳/续租/恢复，取消后排空。
 package main
 import (
 	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"os"
 	"strings"
 	"time"
 	orbit "git.yuntuo.hk/k2safe/orbit/sdk/go"
 )
 func main() {
 	if err := run(); err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)
 	}
 }
 func run() error {
 	token, queue := os.Getenv("ORBIT_TOKEN"), os.Getenv("ORBIT_QUEUE_ID")
 	if path := os.Getenv("ORBIT_CREDENTIALS_FILE"); path != "" {
 		raw, err := os.ReadFile(path)
 		if err != nil {
 			return fmt.Errorf("read private credentials: %w", err)
 		}
 		var credentials struct {
 			Token   string `json:"token"`
 			QueueID string `json:"queue_id"`
 		}
 		if json.Unmarshal(raw, &credentials) != nil {
 			return errors.New("invalid credentials file")
 		}
 		if token == "" {
 			token = credentials.Token
 		}
 		if queue == "" {
 			queue = credentials.QueueID
 		}
 	}
 	client, err := orbit.NewClient(os.Getenv("ORBIT_URL"), orbit.Options{Token: token})
 	if err != nil {
 		return err
 	}
 	operation, err := orbit.NewWorkerMessageID()
 	if err != nil {
 		return err
 	}
 	handler := "text.normalize.runtime." + operation
 	w, err := orbit.NewWorker(client, orbit.WorkerOptions{QueueID: queue, Capacity: 2, ShutdownTimeout: 5 * time.Second, Handlers: []orbit.WorkerHandler{{Capability: orbit.WorkerCapability{Handler: handler, HandlerVersion: "v1", PayloadVersion: "v1"}, Handle: normalize}}})
 	if err != nil {
 		return err
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
 	defer cancel()
 	// 示例先受理，再启动消费者；生产通常是独立的长驻 Worker 进程。
 	var tasks []orbit.Task
 	for i, text := range []string{"  hello orbit  ", "  reusable worker  ", "  durable result  "} {
 		payload, _ := json.Marshal(struct {
 			Text string `json:"text"`
 		}{text})
 		accepted, err := client.SubmitTask(ctx, fmt.Sprintf("runtime-%s-%d", operation, i), orbit.SubmitTaskRequest{QueueID: queue, Handler: handler, HandlerVersion: "v1", PayloadVersion: "v1", Payload: payload, TaskTimeoutMS: 60000, Retry: orbit.RetryPolicy{MaxAttempts: 1, AttemptTimeoutMS: 10000}, RecoverySafety: orbit.RecoveryIdempotent})
 		if err != nil {
 			return err
 		}
 		tasks = append(tasks, accepted.Task)
 	}
 	workerCtx, stop := context.WithCancel(ctx)
 	done := make(chan error, 1)
 	go func() { done <- w.Run(workerCtx) }()
 	// 任一调用失败时也等待有界排空，不在 main 返回时静默丢掉执行中的 Worker。
 	waited := false
 	defer func() {
 		stop()
 		if !waited {
 			<-done
 		}
 	}()
 	for _, task := range tasks {
 		for {
 			current, err := client.GetTask(ctx, task.ID)
 			if err != nil {
 				return err
 			}
 			if current.State == orbit.TaskSucceeded {
 				fmt.Printf("task=%s state=%s result=%s\n", current.ID, current.State, current.Result)
 				break
 			}
 			if current.State == orbit.TaskFailed || current.State == orbit.TaskNeedsReview {
 				return fmt.Errorf("task %s requires attention: %s", current.ID, current.State)
 			}
 			select {
 			case err := <-done:
 				waited = true
 				return fmt.Errorf("Worker stopped before completion: %v", err)
 			case <-ctx.Done():
 				return ctx.Err()
 			case <-time.After(100 * time.Millisecond):
 			}
 		}
 	}
 	stop()
 	err = <-done
 	waited = true
 	if err != nil {
 		return err
 	}
 	stats := w.Stats()
 	if stats.Started != 3 || stats.ReportsConfirmed != 3 || stats.Running != 0 {
 		return errors.New("unexpected Worker completion counts")
 	}
 	fmt.Printf("worker_drained=true started=%d confirmed=%d running=%d\n", stats.Started, stats.ReportsConfirmed, stats.Running)
 	return nil
 }
 func normalize(ctx context.Context, execution orbit.WorkerExecution) (json.RawMessage, error) {
 	var in struct {
 		Text string `json:"text"`
 	}
 	if err := json.Unmarshal(execution.Task.Payload, &in); err != nil {
 		return nil, &orbit.WorkerFailure{Code: "INVALID_TEXT"}
 	}
 	// 模拟可取消的短工作；真实 I/O 也必须使用传入的 ctx。
 	select {
 	case <-ctx.Done():
 		return nil, ctx.Err()
 	case <-time.After(200 * time.Millisecond):
 	}
 	return json.Marshal(struct {
 		Text string `json:"text"`
 	}{Text: strings.ToUpper(strings.TrimSpace(in.Text))})
 }
--- a/sdk/go/worker_handler.go
+++ b/sdk/go/worker_handler.go
@@ -0,0 +1,130 @@
 package orbit
 import (
 	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
 	"io"
 	"strconv"
 	"strings"
 )
 type handlerCompletion struct {
 	attemptID string
 	result    WorkerFinish
 }
 func (w *Worker) invoke(ctx context.Context, handler WorkerHandler, execution WorkerExecution, ref WorkerAttempt, results chan<- handlerCompletion, runDone <-chan struct{}) {
 	out := WorkerFinish{Ref: ref, Outcome: WorkerUnknown, ErrorCode: "HANDLER_ABORTED", Result: json.RawMessage(`{}`)}
 	completed := false
 	defer func() {
 		if recover() != nil {
 			out = unknownHandlerResult(ref, "HANDLER_PANIC")
 		} else if !completed {
 			out = unknownHandlerResult(ref, "HANDLER_ABORTED")
 		}
 		w.running.Add(-1)
 		select {
 		case results <- handlerCompletion{attemptID: ref.AttemptID, result: out}:
 		case <-runDone:
 		}
 	}()
 	if ctx.Err() != nil {
 		out = unknownHandlerResult(ref, "LEASE_LOST")
 		completed = true
 		return
 	}
 	w.started.Add(1)
 	result, err := handler.Handle(ctx, execution)
 	if err == nil {
 		result = append(json.RawMessage(nil), result...)
 		if validHandlerResult(result) {
 			out = WorkerFinish{Ref: ref, Outcome: WorkerSucceeded, Result: result}
 		} else {
 			out = unknownHandlerResult(ref, "INVALID_HANDLER_RESULT")
 		}
 	} else {
 		var known *WorkerFailure
 		if errors.As(err, &known) && known != nil && workerName(known.Code, 64) {
 			details := append(json.RawMessage(nil), known.Details...)
 			if len(details) == 0 {
 				details = json.RawMessage(`{}`)
 			}
 			if validHandlerResult(details) {
 				out = WorkerFinish{Ref: ref, Outcome: WorkerFailed, ErrorCode: known.Code, Result: details}
 			} else {
 				out = unknownHandlerResult(ref, "INVALID_HANDLER_RESULT")
 			}
 		} else if errors.Is(context.Cause(ctx), ErrExecutionLeaseLost) {
 			out = unknownHandlerResult(ref, "LEASE_LOST")
 		} else {
 			out = unknownHandlerResult(ref, "HANDLER_ERROR")
 		}
 	}
 	completed = true
 }
 func unknownHandlerResult(ref WorkerAttempt, code string) WorkerFinish {
 	return WorkerFinish{Ref: ref, Outcome: WorkerUnknown, ErrorCode: code, Result: json.RawMessage(`{}`)}
 }
 // validHandlerResult 提前拒绝服务端无法持久化的结果，避免失效报告无限重报。
 // 只检验数值范围；不把精确业务数字改写成 float64。
 func validHandlerResult(raw json.RawMessage) bool {
 	if len(raw) == 0 || len(raw) > 256<<10 || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
 		return false
 	}
 	// 预留 task.finish 的信封/body 嵌套，避免合法结果单独校验后在帧校验阶段超深。
 	frame := append([]byte(`{"body":{"result":`), raw...)
 	frame = append(frame, []byte(`}}`)...)
 	if validateWorkerJSON(frame) != nil {
 		return false
 	}
 	d := json.NewDecoder(bytes.NewReader(raw))
 	d.UseNumber()
 	for {
 		value, err := d.Token()
 		if err == io.EOF {
 			return true
 		}
 		if err != nil {
 			return false
 		}
 		number, ok := value.(json.Number)
 		if !ok {
 			continue
 		}
 		s := string(number)
 		if len(s) > 256 {
 			return false
 		}
 		if _, err := strconv.ParseFloat(s, 64); err != nil {
 			return false
 		}
 		s = strings.TrimPrefix(s, "-")
 		exponent := 0
 		if i := strings.IndexAny(s, "eE"); i >= 0 {
 			var err error
 			exponent, err = strconv.Atoi(s[i+1:])
 			if err != nil || exponent < -308 || exponent > 308 {
 				return false
 			}
 			s = s[:i]
 		}
 		if i := strings.IndexByte(s, '.'); i >= 0 {
 			exponent -= len(s) - i - 1
 			s = s[:i] + s[i+1:]
 		}
 		s = strings.TrimLeft(s, "0")
 		if s == "" {
 			continue
 		}
 		for strings.HasSuffix(s, "0") {
 			s = s[:len(s)-1]
 			exponent++
 		}
 		if exponent < -308 || exponent > 308 || exponent+len(s)-1 > 308 {
 			return false
 		}
 	}
 }
--- a/sdk/go/worker_integration_test.go
+++ b/sdk/go/worker_integration_test.go
@@ -49,17 +49,24 @@ func integrationWorkerClient(t *testing.T) (*Client, string, string) {
 // 只丢响应，不伪造任务状态，测试凭据不进入 URL 或输出。
 type workerFaultGateway struct {
 	drop    atomic.Value
 	offline atomic.Bool
 	mu      sync.Mutex
 	active  map[*websocket.Conn]struct{}
 	dropped chan string
 	server  *httptest.Server
 }
 func newWorkerFaultGateway(t *testing.T, upstream string) *workerFaultGateway {
 	t.Helper()
-	g := &workerFaultGateway{dropped: make(chan string, 4)}
+	g := &workerFaultGateway{dropped: make(chan string, 4), active: make(map[*websocket.Conn]struct{})}
 	g.drop.Store("")
 	ctx, cancel := context.WithCancel(context.Background())
 	var handlers sync.WaitGroup
 	g.server = httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if g.offline.Load() {
 			http.Error(w, "gateway offline", 503)
 			return
 		}
 		handlers.Add(1)
 		defer handlers.Done()
 		bridge, stop := context.WithCancel(ctx)
@@ -78,6 +85,13 @@ func newWorkerFaultGateway(t *testing.T, upstream string) *workerFaultGateway {
 			return
 		}
 		defer down.CloseNow()
 		g.mu.Lock()
 		g.active[down] = struct{}{}
 		g.mu.Unlock()
 		defer func() { g.mu.Lock(); delete(g.active, down); g.mu.Unlock() }()
 		if g.offline.Load() {
 			return
 		}
 		down.SetReadLimit(512 << 10)
 		var mu sync.Mutex
 		var forwarding sync.WaitGroup
@@ -141,6 +155,17 @@ func newWorkerFaultGateway(t *testing.T, upstream string) *workerFaultGateway {
 	t.Cleanup(func() { cancel(); g.server.Close(); handlers.Wait() })
 	return g
 }
 func (g *workerFaultGateway) disconnectActive() {
 	g.mu.Lock()
 	active := make([]*websocket.Conn, 0, len(g.active))
 	for c := range g.active {
 		active = append(active, c)
 	}
 	g.mu.Unlock()
 	for _, c := range active {
 		c.CloseNow()
 	}
 }
 func (g *workerFaultGateway) expectDrop(t *testing.T, operation string) {
 	t.Helper()
 	select {
--- a/sdk/go/worker_lease_guard.go
+++ b/sdk/go/worker_lease_guard.go
@@ -0,0 +1,76 @@
 package orbit
 import (
 	"context"
 	"sync"
 	"time"
 )
 // executionGuard 独立于网络控制取消处理器，已到期/取消的上下文永不恢复。
 type executionGuard struct {
 	ctx      context.Context
 	cancel   context.CancelCauseFunc
 	mu       sync.Mutex
 	deadline time.Time
 	wake     chan struct{}
 	done     chan struct{}
 }
 func newExecutionGuard(parent context.Context, lease WorkerLease) (*executionGuard, bool) {
 	deadline, ok := lease.ExecutionDeadline()
 	if !ok {
 		return nil, false
 	}
 	ctx, cancel := context.WithCancelCause(parent)
 	g := &executionGuard{ctx: ctx, cancel: cancel, deadline: deadline, wake: make(chan struct{}, 1), done: make(chan struct{})}
 	go g.watch()
 	return g, true
 }
 func (g *executionGuard) watch() {
 	defer close(g.done)
 	timer := time.NewTimer(time.Until(g.until()))
 	defer timer.Stop()
 	for {
 		select {
 		case <-g.ctx.Done():
 			return
 		case <-g.wake:
 		case <-timer.C:
 		}
 		g.mu.Lock()
 		remaining := time.Until(g.deadline)
 		if remaining <= 0 {
 			g.cancel(ErrExecutionLeaseLost)
 			g.mu.Unlock()
 			return
 		}
 		timer.Reset(remaining)
 		g.mu.Unlock()
 	}
 }
 func (g *executionGuard) update(lease WorkerLease) bool {
 	g.mu.Lock()
 	defer g.mu.Unlock()
 	if g.ctx.Err() != nil || !time.Now().Before(g.deadline) {
 		g.cancel(ErrExecutionLeaseLost)
 		return false
 	}
 	deadline, ok := lease.ExecutionDeadline()
 	if !lease.Active || lease.State != "RUNNING" {
 		g.cancel(ErrExecutionLeaseLost)
 		return false
 	}
 	// Lease 是新鲜核验，不是历史 Receipt。新会话可能缩短有效窗口，必须遵守。
 	if !ok {
 		g.cancel(ErrExecutionLeaseLost)
 		return false
 	}
 	g.deadline = deadline
 	select {
 	case g.wake <- struct{}{}:
 	default:
 	}
 	return true
 }
 func (g *executionGuard) until() time.Time { g.mu.Lock(); defer g.mu.Unlock(); return g.deadline }
 func (g *executionGuard) stop(cause error) { g.cancel(cause); <-g.done }
--- a/sdk/go/worker_runtime.go
+++ b/sdk/go/worker_runtime.go
@@ -0,0 +1,543 @@
 package orbit
 import (
 	"context"
 	"errors"
 	"math/rand/v2"
 	"sync"
 	"sync/atomic"
 	"time"
 )
 type runtimeAttempt struct {
 	assignment                 WorkerAssignment
 	startID, renewID, finishID string
 	guard                      *executionGuard
 	invoked, returned, lost    bool
 	result                     WorkerFinish
 	nextTry, nextRenew         time.Time
 	retryDelay                 time.Duration
 }
 type runtimeCommand struct {
 	kind     string
 	id       string
 	job      *runtimeAttempt
 	capacity WorkerCapacity
 	conn     *WorkerConnection
 }
 type runtimeReply struct {
 	command *runtimeCommand
 	result  WorkerCommandResult
 	welcome WorkerWelcome
 	err     error
 }
 type runtimeConnected struct {
 	conn   *WorkerConnection
 	leases map[string]WorkerLease
 	err    error
 }
 type workerRuntime struct {
 	worker                   *Worker
 	ctx                      context.Context
 	jobs                     map[string]*runtimeAttempt
 	order                    []string
 	cursor                   int
 	conn                     *WorkerConnection
 	command                  *runtimeCommand
 	connecting               bool
 	connectedOnce            bool
 	draining, drainConfirmed bool
 	capacity                 uint32
 	sequence                 uint64
 	heartbeat, dialAt        time.Time
 	backoff                  time.Duration
 	results                  chan handlerCompletion
 	replies                  chan runtimeReply
 	connections              chan runtimeConnected
 	wg                       sync.WaitGroup
 }
 // Run 持续消费直到 ctx 取消或不可恢复的认证/协议错误。取消后先排空并在
 // ShutdownTimeout 内收集在途结果；正常收尾返回 nil，超时返回 *WorkerRunError。
 // 已到期的处理器上下文不会因重连复活；每个已知尝试在本进程最多调用一次处理器。
 func (w *Worker) Run(parent context.Context) error {
 	if !w.used.CompareAndSwap(false, true) {
 		return ErrWorkerAlreadyRun
 	}
 	defer close(w.events)
 	if parent.Err() != nil {
 		return nil
 	}
 	ctx, cancel := context.WithCancel(context.WithoutCancel(parent))
 	var shutdownExpired atomic.Bool
 	watchDone := make(chan struct{})
 	go func() {
 		defer close(watchDone)
 		select {
 		case <-ctx.Done():
 			return
 		case <-parent.Done():
 		}
 		timer := time.NewTimer(w.options.ShutdownTimeout)
 		defer timer.Stop()
 		select {
 		case <-ctx.Done():
 		case <-timer.C:
 			shutdownExpired.Store(true)
 			cancel()
 		}
 	}()
 	r := &workerRuntime{worker: w, ctx: ctx, jobs: make(map[string]*runtimeAttempt), backoff: w.options.ReconnectMinDelay, results: make(chan handlerCompletion, w.options.Capacity), replies: make(chan runtimeReply, 2), connections: make(chan runtimeConnected, 1)}
 	defer func() {
 		cancel()
 		if r.conn != nil {
 			r.conn.Close()
 		}
 		for _, j := range r.jobs {
 			if j.guard != nil {
 				j.guard.stop(context.Canceled)
 			}
 		}
 		r.wg.Wait()
 		// 连接可能在退出与交付结果之间成功，仍需关闭；不留下新会话连接。
 		select {
 		case c := <-r.connections:
 			if c.conn != nil {
 				c.conn.Close()
 			}
 		default:
 		}
 		<-watchDone
 	}()
 	tick := time.NewTicker(20 * time.Millisecond)
 	defer tick.Stop()
 	stop := parent.Done()
 	for {
 		if ctx.Err() != nil {
 			cause := ctx.Err()
 			if shutdownExpired.Load() {
 				cause = ErrWorkerShutdownTimeout
 			}
 			return r.failure(cause)
 		}
 		if parent.Err() != nil && !r.draining {
 			r.draining = true
 			stop = nil
 			w.emit(WorkerEvent{Type: "draining"})
 		}
 		r.observeExpired()
 		if r.conn != nil && r.conn.Err() != nil {
 			if err := r.disconnect(r.conn.Err()); err != nil {
 				return r.failure(err)
 			}
 		}
 		// drain ACK 之前的派发已被底层读取器排进队列，收齐后才能宣布排空。
 		if r.conn != nil {
 			for len(r.conn.assignments) > 0 {
 				if err := r.accept(<-r.conn.assignments); err != nil {
 					return r.failure(err)
 				}
 			}
 		}
 		if r.draining && len(r.jobs) == 0 && (r.drainConfirmed || !r.connectedOnce && !r.connecting) {
 			return nil
 		}
 		if r.conn == nil && !r.connecting && !time.Now().Before(r.dialAt) {
 			r.connect()
 		}
 		if r.conn != nil && r.command == nil {
 			if err := r.dispatch(); err != nil {
 				return r.failure(err)
 			}
 		}
 		var assignments <-chan WorkerAssignment
 		var closed <-chan struct{}
 		if r.conn != nil {
 			assignments = r.conn.assignments
 			closed = r.conn.Done()
 		}
 		select {
 		case <-ctx.Done():
 		case <-stop:
 			stop = nil
 		case <-tick.C:
 		case <-closed:
 		case a := <-assignments:
 			if r.conn.Err() == nil {
 				if err := r.accept(a); err != nil {
 					return r.failure(err)
 				}
 			}
 		case done := <-r.results:
 			if j := r.jobs[done.attemptID]; j != nil {
 				j.returned = true
 				j.result = done.result
 				j.nextTry = time.Time{}
 			}
 		case reply := <-r.replies:
 			if err := r.receive(reply); err != nil {
 				return r.failure(err)
 			}
 		case connected := <-r.connections:
 			if err := r.establish(connected); err != nil {
 				return r.failure(err)
 			}
 		}
 	}
 }
 func (r *workerRuntime) failure(err error) error {
 	return &WorkerRunError{Cause: err, Unconfirmed: len(r.jobs), Running: r.worker.running.Load()}
 }
 func (r *workerRuntime) event(j *runtimeAttempt, kind, code string) {
 	r.worker.emit(WorkerEvent{Type: kind, TaskID: j.assignment.Task.ID, AttemptID: j.assignment.AttemptID, Code: code})
 }
 func (r *workerRuntime) accept(a WorkerAssignment) error {
 	if j := r.jobs[a.AttemptID]; j != nil {
 		if j.assignment.Attempt() != a.Attempt() {
 			return ErrWorkerProtocol
 		}
 		return nil
 	}
 	// 运行中失去授权但不退出的处理器仍占物理槽；允许接收一轮已在网络中的预占，
 	// 不突破处理器容量，也不让待核对身份无限累积。
 	if len(r.jobs) >= 2*int(r.worker.options.Capacity) {
 		return ErrWorkerBackpressure
 	}
 	id, err := NewWorkerMessageID()
 	if err != nil {
 		return err
 	}
 	r.jobs[a.AttemptID] = &runtimeAttempt{assignment: a, startID: id}
 	r.order = append(r.order, a.AttemptID)
 	return nil
 }
 func (r *workerRuntime) remove(j *runtimeAttempt) {
 	if j.guard != nil {
 		j.guard.stop(context.Canceled)
 	}
 	delete(r.jobs, j.assignment.AttemptID)
 	for i, id := range r.order {
 		if id == j.assignment.AttemptID {
 			r.order = append(r.order[:i], r.order[i+1:]...)
 			break
 		}
 	}
 	if len(r.order) > 0 {
 		r.cursor %= len(r.order)
 	} else {
 		r.cursor = 0
 	}
 }
 func (r *workerRuntime) observeExpired() {
 	for _, j := range r.jobs {
 		if j.guard != nil && j.guard.ctx.Err() != nil && !j.lost {
 			j.lost = true
 			r.event(j, "lease_lost", "LEASE_LOST")
 		}
 	}
 }
 func (r *workerRuntime) desiredCapacity() uint32 {
 	if r.draining {
 		return 0
 	}
 	ghosts := uint32(0)
 	for _, j := range r.jobs {
 		if j.returned || j.lost {
 			ghosts++
 		}
 	}
 	if ghosts >= r.worker.options.Capacity {
 		return 0
 	}
 	return r.worker.options.Capacity - ghosts
 }
 func (r *workerRuntime) connect() {
 	r.connecting = true
 	if r.connectedOnce {
 		r.worker.reconnects.Add(1)
 		r.worker.emit(WorkerEvent{Type: "reconnecting"})
 	}
 	refs := make([]WorkerAttempt, 0, len(r.jobs))
 	for _, j := range r.jobs {
 		refs = append(refs, j.assignment.Attempt())
 	}
 	r.wg.Add(1)
 	go func() {
 		defer r.wg.Done()
 		ctx, stop := context.WithTimeout(r.ctx, 30*time.Second)
 		defer stop()
 		c, err := r.worker.client.DialWorker(ctx, r.worker.registration)
 		result := runtimeConnected{conn: c, err: err, leases: make(map[string]WorkerLease, len(refs))}
 		if err == nil {
 			for _, ref := range refs {
 				id, e := NewWorkerMessageID()
 				if e != nil {
 					result.err = e
 					break
 				}
 				lease, e := c.Resume(ctx, id, ref)
 				if e != nil {
 					result.err = e
 					break
 				}
 				result.leases[ref.AttemptID] = lease
 			}
 		}
 		if result.err != nil && c != nil {
 			c.Close()
 			result.conn = nil
 		}
 		select {
 		case r.connections <- result:
 		case <-r.ctx.Done():
 			if result.conn != nil {
 				result.conn.Close()
 			}
 		}
 	}()
 }
 func (r *workerRuntime) establish(c runtimeConnected) error {
 	r.connecting = false
 	if c.err != nil {
 		if !workerRetryable(c.err) {
 			return c.err
 		}
 		r.deferReconnect()
 		return nil
 	}
 	r.conn = c.conn
 	r.connectedOnce = true
 	r.sequence = 0
 	r.heartbeat = time.Time{}
 	r.capacity = ^uint32(0)
 	r.drainConfirmed = false
 	r.draining = r.draining || c.conn.Welcome().Draining
 	for id, lease := range c.leases {
 		j := r.jobs[id]
 		if j == nil {
 			continue
 		}
 		if j.guard != nil {
 			if !j.guard.update(lease) {
 				j.lost = true
 				r.event(j, "lease_lost", "LEASE_LOST")
 			}
 			j.nextRenew = time.Time{}
 		}
 		if !j.invoked && !lease.Active {
 			r.event(j, "lease_lost", "NOT_STARTED")
 			r.remove(j)
 		}
 	}
 	r.worker.emit(WorkerEvent{Type: "connected"})
 	return nil
 }
 func (r *workerRuntime) deferReconnect() {
 	min := r.worker.options.ReconnectMinDelay
 	r.dialAt = time.Now().Add(min + time.Duration(rand.Int64N(int64(r.backoff-min)+1)))
 	r.backoff = minDuration(r.backoff*2, r.worker.options.ReconnectMaxDelay)
 }
 func (r *workerRuntime) disconnect(err error) error {
 	if r.conn != nil {
 		r.conn.Close()
 		r.conn = nil
 	}
 	r.command = nil
 	if !workerRetryable(err) {
 		return err
 	}
 	r.deferReconnect()
 	return nil
 }
 func workerRetryable(err error) bool {
 	if errors.Is(err, ErrWorkerDisconnected) || errors.Is(err, ErrWorkerClosed) || errors.Is(err, ErrWorkerBackpressure) || errors.Is(err, context.DeadlineExceeded) {
 		return true
 	}
 	var control *WorkerError
 	if errors.As(err, &control) {
 		return control.Code == "STALE_SESSION" || control.Code == "UNAVAILABLE"
 	}
 	var httpErr *HTTPError
 	return errors.As(err, &httpErr) && (httpErr.StatusCode == 429 || httpErr.StatusCode >= 500)
 }
 func minDuration(a, b time.Duration) time.Duration {
 	if a < b {
 		return a
 	}
 	return b
 }
 func (r *workerRuntime) dispatch() error {
 	now := time.Now()
 	capacity := r.desiredCapacity()
 	if !now.Before(r.heartbeat) || capacity != r.capacity || r.draining && !r.drainConfirmed {
 		id, err := NewWorkerMessageID()
 		if err != nil {
 			return err
 		}
 		r.sequence++
 		r.launch(&runtimeCommand{kind: "capacity", id: id, capacity: WorkerCapacity{Sequence: r.sequence, Capacity: capacity, Drain: r.draining}})
 		return nil
 	}
 	// 结果优先释放占用；其后照顾临近续租，再批准新处理器。每类内部轮转。
 	for _, kind := range []string{"finish", "renew", "start"} {
 		for n := 0; n < len(r.order); n++ {
 			i := (r.cursor + n) % len(r.order)
 			j := r.jobs[r.order[i]]
 			if now.Before(j.nextTry) {
 				continue
 			}
 			var id *string
 			switch kind {
 			case "finish":
 				if !j.returned {
 					continue
 				}
 				id = &j.finishID
 			case "renew":
 				if !j.invoked || j.lost || j.returned || now.Before(j.nextRenew) {
 					continue
 				}
 				id = &j.renewID
 			case "start":
 				if j.invoked || r.worker.running.Load() >= int64(r.worker.options.Capacity) {
 					continue
 				}
 				id = &j.startID
 			}
 			if *id == "" {
 				var err error
 				*id, err = NewWorkerMessageID()
 				if err != nil {
 					return err
 				}
 			}
 			r.cursor = (i + 1) % len(r.order)
 			r.launch(&runtimeCommand{kind: kind, id: *id, job: j})
 			return nil
 		}
 	}
 	return nil
 }
 func (r *workerRuntime) launch(command *runtimeCommand) {
 	command.conn = r.conn
 	r.command = command
 	// 操作所需值在 goroutine 启动前复制；运行器事件循环独占可变尝试状态。
 	var ref WorkerAttempt
 	var finish WorkerFinish
 	if command.job != nil {
 		ref = command.job.assignment.Attempt()
 		finish = command.job.result
 	}
 	r.wg.Add(1)
 	go func() {
 		defer r.wg.Done()
 		reply := runtimeReply{command: command}
 		switch command.kind {
 		case "capacity":
 			reply.welcome, reply.err = command.conn.Capacity(r.ctx, command.id, command.capacity)
 		case "start":
 			reply.result, reply.err = command.conn.Start(r.ctx, command.id, ref)
 		case "renew":
 			reply.result, reply.err = command.conn.Renew(r.ctx, command.id, ref)
 		case "finish":
 			reply.result, reply.err = command.conn.Finish(r.ctx, command.id, finish)
 		}
 		select {
 		case r.replies <- reply:
 		case <-r.ctx.Done():
 		}
 	}()
 }
 func (r *workerRuntime) receive(reply runtimeReply) error {
 	command := reply.command
 	if r.command != command || command.conn != r.conn {
 		return nil
 	}
 	r.command = nil
 	j := command.job
 	if reply.err != nil {
 		var control *WorkerError
 		if j != nil && errors.As(reply.err, &control) {
 			switch control.Code {
 			case "LEASE_LOST":
 				if command.kind == "finish" {
 					return reply.err
 				}
 				if j.guard != nil {
 					j.guard.stop(ErrExecutionLeaseLost)
 					j.lost = true
 					r.event(j, "lease_lost", control.Code)
 				} else {
 					r.remove(j)
 				}
 				return nil
 			case "EXECUTION_PAUSED", "UNAVAILABLE":
 				if j.retryDelay == 0 {
 					j.retryDelay = 200 * time.Millisecond
 				} else {
 					j.retryDelay = minDuration(j.retryDelay*2, 5*time.Second)
 				}
 				j.nextTry = time.Now().Add(j.retryDelay)
 				return nil
 			}
 		}
 		if workerRetryable(reply.err) {
 			return r.disconnect(reply.err)
 		}
 		return reply.err
 	}
 	r.backoff = r.worker.options.ReconnectMinDelay
 	if command.kind == "capacity" {
 		r.capacity = command.capacity.Capacity
 		r.drainConfirmed = command.capacity.Drain && reply.welcome.Draining
 		r.heartbeat = time.Now().Add(minDuration(5*time.Second, reply.welcome.ExpiresAt.Sub(reply.welcome.ServerTime)/3))
 		return nil
 	}
 	if command.kind == "finish" {
 		if reply.result.Receipt.Disposition == "APPLIED" {
 			r.worker.reports.Add(1)
 			r.event(j, "result_applied", string(reply.result.Receipt.TaskState))
 		} else {
 			r.worker.evidence.Add(1)
 			r.event(j, "result_evidence", string(reply.result.Receipt.TaskState))
 		}
 		r.remove(j)
 		return nil
 	}
 	if command.kind == "start" {
 		guard, ok := newExecutionGuard(r.ctx, reply.result.Lease)
 		if !ok {
 			r.event(j, "lease_lost", "START_NOT_AUTHORIZED")
 			r.remove(j)
 			return nil
 		}
 		j.guard = guard
 		j.invoked = true
 		r.worker.running.Add(1)
 		task := j.assignment.Task
 		task.Payload = append([]byte(nil), task.Payload...)
 		task.Result = append([]byte(nil), task.Result...)
 		execution := WorkerExecution{Task: task, AttemptID: j.assignment.AttemptID, Epoch: j.assignment.Epoch}
 		handler := r.worker.handlers[WorkerCapability{Handler: task.Handler, HandlerVersion: task.HandlerVersion, PayloadVersion: task.PayloadVersion}]
 		r.event(j, "handler_started", "")
 		go r.worker.invoke(guard.ctx, handler, execution, j.assignment.Attempt(), r.results, r.ctx.Done())
 	} else {
 		r.worker.renewals.Add(1)
 		j.renewID = ""
 		if !j.guard.update(reply.result.Lease) {
 			j.lost = true
 			r.event(j, "lease_lost", "LEASE_LOST")
 		}
 	}
 	j.nextTry = time.Time{}
 	j.retryDelay = 0
 	if !j.lost {
 		j.nextRenew = time.Now().Add(max(20*time.Millisecond, time.Until(j.guard.until())/3))
 	}
 	return nil
 }
--- a/sdk/go/worker_runtime_integration_test.go
+++ b/sdk/go/worker_runtime_integration_test.go
@@ -0,0 +1,357 @@
 package orbit
 import (
 	"context"
 	"encoding/json"
 	"errors"
 	"sync/atomic"
 	"testing"
 	"time"
 )
 func runtimeTask(t *testing.T, ctx context.Context, c *Client, queue, handler string, timeout uint64) Task {
 	t.Helper()
 	out, err := c.SubmitTask(ctx, "runtime-"+workerTestID(t), SubmitTaskRequest{QueueID: queue, Handler: handler, HandlerVersion: "v1", PayloadVersion: "v1", Payload: json.RawMessage(`{"sequence":9007199254740993}`), TaskTimeoutMS: 120000, Retry: RetryPolicy{MaxAttempts: 1, AttemptTimeoutMS: timeout}})
 	if err != nil {
 		t.Fatal(err)
 	}
 	return out.Task
 }
 func runtimeHandler(name string, handle func(context.Context, WorkerExecution) (json.RawMessage, error)) WorkerHandler {
 	return WorkerHandler{Capability: WorkerCapability{Handler: name, HandlerVersion: "v1", PayloadVersion: "v1"}, Handle: handle}
 }
 func waitRuntimeState(t *testing.T, ctx context.Context, c *Client, id string, state TaskState) Task {
 	t.Helper()
 	for {
 		task, err := c.GetTask(ctx, id)
 		if err != nil {
 			t.Fatal(err)
 		}
 		if task.State == state {
 			return task
 		}
 		select {
 		case <-ctx.Done():
 			t.Fatalf("task did not reach %s", state)
 		case <-time.After(50 * time.Millisecond):
 		}
 	}
 }
 func TestIntegrationWorkerRuntimeACKLossRenewAndDrain(t *testing.T) {
 	api, queue, token := integrationWorkerClient(t)
 	ctx, cancel := context.WithTimeout(context.Background(), 55*time.Second)
 	defer cancel()
 	g := newWorkerFaultGateway(t, api.baseURL)
 	client, err := NewClient(g.server.URL, Options{Token: token, HTTPClient: g.server.Client()})
 	if err != nil {
 		t.Fatal(err)
 	}
 	name := "runtime.renew." + workerTestID(t)
 	entered := make(chan struct{})
 	var calls atomic.Int32
 	w, err := NewWorker(client, WorkerOptions{QueueID: queue, Capacity: 1, ShutdownTimeout: 45 * time.Second, Handlers: []WorkerHandler{runtimeHandler(name, func(work context.Context, e WorkerExecution) (json.RawMessage, error) {
 		calls.Add(1)
 		close(entered)
 		// 必须跨过服务端最初的 30 秒租约；只有自动续租成功才能获得 APPLIED。
 		select {
 		case <-work.Done():
 			return nil, work.Err()
 		case <-time.After(32 * time.Second):
 			return json.RawMessage(`{"sequence":9007199254740993,"done":true}`), nil
 		}
 	})}})
 	if err != nil {
 		t.Fatal(err)
 	}
 	task := runtimeTask(t, ctx, api, queue, name, 90000)
 	g.drop.Store("task.start")
 	runCtx, stop := context.WithCancel(ctx)
 	defer stop()
 	done := make(chan error, 1)
 	go func() { done <- w.Run(runCtx) }()
 	g.expectDrop(t, "task.start")
 	select {
 	case <-entered:
 	case err := <-done:
 		t.Fatalf("Worker stopped before handler: %v", err)
 	case <-ctx.Done():
 		t.Fatal("handler did not start")
 	}
 	g.drop.Store("task.finish")
 	stop() // 取消 Run 只进入排空，不能立即取消正在执行的函数。
 	select {
 	case err := <-done:
 		if err != nil {
 			t.Fatal(err)
 		}
 	case <-ctx.Done():
 		t.Fatal("Worker did not finish within grace")
 	}
 	g.expectDrop(t, "task.finish")
 	current := waitRuntimeState(t, ctx, api, task.ID, TaskSucceeded)
 	stats := w.Stats()
 	if calls.Load() != 1 || stats.Started != 1 || stats.Running != 0 || stats.ReportsConfirmed != 1 || stats.Reconnects < 2 || stats.RenewalsConfirmed < 2 || current.AttemptCount != 1 || string(current.Result) != `{"sequence":9007199254740993,"done":true}` {
 		t.Fatalf("automatic execution invariant failed: calls=%d stats=%+v attempts=%d", calls.Load(), stats, current.AttemptCount)
 	}
 	// 仍在等待的同类工作不能被已排空的进程领取。
 	waiting := runtimeTask(t, ctx, api, queue, name, 10000)
 	observed, err := api.GetTask(ctx, waiting.ID)
 	if err != nil {
 		t.Fatal(err)
 	}
 	if observed.State != TaskWaiting {
 		t.Fatal("drained Worker accepted another task")
 	}
 	if _, err := api.CancelTask(ctx, observed.ID, "cleanup-"+workerTestID(t), CancelTaskRequest{ExpectedRevision: observed.Revision, Reason: "finish runtime drain regression"}); err != nil {
 		t.Fatal(err)
 	}
 }
 func TestIntegrationWorkerRuntimeUnknownAndUncooperativeShutdown(t *testing.T) {
 	api, queue, _ := integrationWorkerClient(t)
 	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
 	defer cancel()
 	for _, test := range []struct {
 		name   string
 		handle func(context.Context, WorkerExecution) (json.RawMessage, error)
 		state  TaskState
 	}{
 		{"known", func(context.Context, WorkerExecution) (json.RawMessage, error) {
 			return nil, &WorkerFailure{Code: "INVALID_OBJECT"}
 		}, TaskFailed},
 		{"unknown", func(context.Context, WorkerExecution) (json.RawMessage, error) {
 			return nil, errors.New("external request timed out with private details")
 		}, TaskNeedsReview},
 		{"panic", func(context.Context, WorkerExecution) (json.RawMessage, error) { panic("private panic") }, TaskNeedsReview},
 	} {
 		t.Run(test.name, func(t *testing.T) {
 			name := "runtime." + test.name + "." + workerTestID(t)
 			w, err := NewWorker(api, WorkerOptions{QueueID: queue, Capacity: 1, Handlers: []WorkerHandler{runtimeHandler(name, test.handle)}})
 			if err != nil {
 				t.Fatal(err)
 			}
 			task := runtimeTask(t, ctx, api, queue, name, 5000)
 			run, stop := context.WithCancel(ctx)
 			done := make(chan error, 1)
 			go func() { done <- w.Run(run) }()
 			defer stop()
 			waitRuntimeState(t, ctx, api, task.ID, test.state)
 			stop()
 			select {
 			case err := <-done:
 				if err != nil {
 					t.Fatal(err)
 				}
 			case <-ctx.Done():
 				t.Fatal("classification Worker did not stop")
 			}
 		})
 	}
 	t.Run("uncooperative", func(t *testing.T) {
 		name := "runtime.uncooperative." + workerTestID(t)
 		entered, release, returned := make(chan struct{}), make(chan struct{}), make(chan struct{})
 		defer close(release)
 		w, err := NewWorker(api, WorkerOptions{QueueID: queue, Capacity: 1, ShutdownTimeout: 250 * time.Millisecond, Handlers: []WorkerHandler{runtimeHandler(name, func(context.Context, WorkerExecution) (json.RawMessage, error) {
 			close(entered)
 			<-release
 			close(returned)
 			return json.RawMessage(`{}`), nil
 		})}})
 		if err != nil {
 			t.Fatal(err)
 		}
 		runtimeTask(t, ctx, api, queue, name, 1500)
 		run, stop := context.WithCancel(ctx)
 		done := make(chan error, 1)
 		go func() { done <- w.Run(run) }()
 		defer stop()
 		select {
 		case <-entered:
 		case <-ctx.Done():
 			t.Fatal("handler did not enter")
 		}
 		began := time.Now()
 		stop()
 		select {
 		case err := <-done:
 			var stopped *WorkerRunError
 			if !errors.As(err, &stopped) || !errors.Is(err, ErrWorkerShutdownTimeout) || stopped.Running != 1 || stopped.Unconfirmed != 1 {
 				t.Fatalf("uncooperative handler hidden: %v", err)
 			}
 		case <-time.After(2 * time.Second):
 			t.Fatal("shutdown waited forever for handler")
 		}
 		if time.Since(began) > time.Second {
 			t.Fatal("shutdown exceeded bounded grace")
 		}
 		select {
 		case <-returned:
 			t.Fatal("SDK claimed to kill uncooperative handler")
 		default:
 		}
 	})
 }
 func TestIntegrationWorkerRuntimeLeaseLossCancelsAndDoesNotRevive(t *testing.T) {
 	api, queue, _ := integrationWorkerClient(t)
 	ctx, cancel := context.WithTimeout(context.Background(), 12*time.Second)
 	defer cancel()
 	name := "runtime.expired." + workerTestID(t)
 	cause := make(chan error, 1)
 	w, err := NewWorker(api, WorkerOptions{QueueID: queue, Capacity: 1, Handlers: []WorkerHandler{runtimeHandler(name, func(work context.Context, _ WorkerExecution) (json.RawMessage, error) {
 		<-work.Done()
 		cause <- context.Cause(work)
 		return nil, work.Err()
 	})}})
 	if err != nil {
 		t.Fatal(err)
 	}
 	task := runtimeTask(t, ctx, api, queue, name, 1400)
 	run, stop := context.WithCancel(ctx)
 	done := make(chan error, 1)
 	go func() { done <- w.Run(run) }()
 	defer stop()
 	select {
 	case err := <-cause:
 		if !errors.Is(err, ErrExecutionLeaseLost) {
 			t.Fatal(err)
 		}
 	case <-ctx.Done():
 		t.Fatal("handler did not observe lease cancellation")
 	}
 	waitRuntimeState(t, ctx, api, task.ID, TaskNeedsReview)
 	stop()
 	select {
 	case err := <-done:
 		if err != nil {
 			t.Fatal(err)
 		}
 	case <-ctx.Done():
 		t.Fatal("Worker did not stop")
 	}
 	if w.Stats().Started != 1 {
 		t.Fatal("expired handler was invoked again")
 	}
 }
 func TestIntegrationWorkerRuntimeOutageCancelsAndReplaysEvidence(t *testing.T) {
 	api, queue, token := integrationWorkerClient(t)
 	ctx, cancel := context.WithTimeout(context.Background(), 18*time.Second)
 	defer cancel()
 	g := newWorkerFaultGateway(t, api.baseURL)
 	client, err := NewClient(g.server.URL, Options{Token: token, HTTPClient: g.server.Client()})
 	if err != nil {
 		t.Fatal(err)
 	}
 	name := "runtime.outage." + workerTestID(t)
 	entered, cancelled := make(chan struct{}), make(chan error, 1)
 	w, err := NewWorker(client, WorkerOptions{QueueID: queue, Capacity: 1, ReconnectMaxDelay: time.Second, Handlers: []WorkerHandler{runtimeHandler(name, func(work context.Context, _ WorkerExecution) (json.RawMessage, error) {
 		close(entered)
 		<-work.Done()
 		cancelled <- context.Cause(work)
 		return nil, work.Err()
 	})}})
 	if err != nil {
 		t.Fatal(err)
 	}
 	task := runtimeTask(t, ctx, api, queue, name, 2000)
 	run, stop := context.WithCancel(ctx)
 	done := make(chan error, 1)
 	go func() { done <- w.Run(run) }()
 	defer stop()
 	select {
 	case <-entered:
 	case <-ctx.Done():
 		t.Fatal("handler did not start")
 	}
 	g.offline.Store(true)
 	g.disconnectActive()
 	select {
 	case cause := <-cancelled:
 		if !errors.Is(cause, ErrExecutionLeaseLost) {
 			t.Fatal(cause)
 		}
 	case <-ctx.Done():
 		t.Fatal("disconnected handler ignored local expiry")
 	}
 	waitRuntimeState(t, ctx, api, task.ID, TaskNeedsReview)
 	g.offline.Store(false)
 	for w.Stats().EvidenceConfirmed != 1 {
 		select {
 		case err := <-done:
 			t.Fatalf("Worker stopped before evidence replay: %v", err)
 		case <-ctx.Done():
 			t.Fatal("pending result was not replayed")
 		case <-time.After(50 * time.Millisecond):
 		}
 	}
 	stop()
 	select {
 	case err := <-done:
 		if err != nil {
 			t.Fatal(err)
 		}
 	case <-ctx.Done():
 		t.Fatal("Worker did not stop")
 	}
 	current, err := api.GetTask(ctx, task.ID)
 	if err != nil {
 		t.Fatal(err)
 	}
 	if w.Stats().Started != 1 || current.AttemptCount != 1 || current.State != TaskNeedsReview || len(current.Result) != 0 {
 		t.Fatal("outage revived handler or promoted late evidence")
 	}
 }
 func TestIntegrationWorkerRuntimeConcurrency(t *testing.T) {
 	api, queue, _ := integrationWorkerClient(t)
 	ctx, cancel := context.WithTimeout(context.Background(), 18*time.Second)
 	defer cancel()
 	name := "runtime.concurrency." + workerTestID(t)
 	var running, peak atomic.Int32
 	w, err := NewWorker(api, WorkerOptions{QueueID: queue, Capacity: 2, Handlers: []WorkerHandler{runtimeHandler(name, func(work context.Context, _ WorkerExecution) (json.RawMessage, error) {
 		value := running.Add(1)
 		defer running.Add(-1)
 		for old := peak.Load(); value > old; old = peak.Load() {
 			if peak.CompareAndSwap(old, value) {
 				break
 			}
 		}
 		select {
 		case <-work.Done():
 			return nil, work.Err()
 		case <-time.After(300 * time.Millisecond):
 			return json.RawMessage(`{"done":true}`), nil
 		}
 	})}})
 	if err != nil {
 		t.Fatal(err)
 	}
 	var tasks []Task
 	for range 6 {
 		tasks = append(tasks, runtimeTask(t, ctx, api, queue, name, 10000))
 	}
 	run, stop := context.WithCancel(ctx)
 	done := make(chan error, 1)
 	go func() { done <- w.Run(run) }()
 	defer stop()
 	for _, task := range tasks {
 		current := waitRuntimeState(t, ctx, api, task.ID, TaskSucceeded)
 		if current.AttemptCount != 1 {
 			t.Fatal("unexpected new attempt")
 		}
 	}
 	stop()
 	select {
 	case err := <-done:
 		if err != nil {
 			t.Fatal(err)
 		}
 	case <-ctx.Done():
 		t.Fatal("Worker did not drain")
 	}
 	if peak.Load() != 2 || running.Load() != 0 || w.Stats().Started != 6 || w.Stats().ReportsConfirmed != 6 {
 		t.Fatalf("concurrency invariant failed: peak=%d stats=%+v", peak.Load(), w.Stats())
 	}
 }
--- a/sdk/go/worker_runtime_test.go
+++ b/sdk/go/worker_runtime_test.go
@@ -0,0 +1,181 @@
 package orbit
 import (
 	"context"
 	"encoding/json"
 	"errors"
 	"net/http"
 	"net/http/httptest"
 	"runtime"
 	"strings"
 	"testing"
 	"time"
 )
 func guardLease(duration time.Duration) WorkerLease {
 	return WorkerLease{Active: true, State: "RUNNING", deadline: time.Now().Add(duration)}
 }
 func TestExecutionGuardRenewsShortensAndNeverRevives(t *testing.T) {
 	parent, cancel := context.WithCancel(context.Background())
 	defer cancel()
 	g, ok := newExecutionGuard(parent, guardLease(80*time.Millisecond))
 	if !ok {
 		t.Fatal("missing guard")
 	}
 	defer g.stop(context.Canceled)
 	if !g.update(guardLease(500 * time.Millisecond)) {
 		t.Fatal("renew rejected")
 	}
 	select {
 	case <-g.ctx.Done():
 		t.Fatal("old lease cancelled a renewed handler")
 	case <-time.After(100 * time.Millisecond):
 	}
 	if !g.update(guardLease(35 * time.Millisecond)) {
 		t.Fatal("new short session rejected")
 	}
 	select {
 	case <-g.ctx.Done():
 	case <-time.After(200 * time.Millisecond):
 		t.Fatal("shorter session did not cancel handler")
 	}
 	if !errors.Is(context.Cause(g.ctx), ErrExecutionLeaseLost) {
 		t.Fatal(context.Cause(g.ctx))
 	}
 	if g.update(guardLease(time.Minute)) {
 		t.Fatal("expired handler revived")
 	}
 }
 func TestHandlerOutcomesAndAbort(t *testing.T) {
 	ref := WorkerAttempt{TaskID: workerTestTask, AttemptID: workerTestAttempt, Epoch: 1}
 	for _, test := range []struct {
 		name string
 		fn   func(context.Context, WorkerExecution) (json.RawMessage, error)
 		out  WorkerOutcome
 		code string
 	}{
 		{"success", func(context.Context, WorkerExecution) (json.RawMessage, error) {
 			return json.RawMessage(`{"n":9007199254740993}`), nil
 		}, WorkerSucceeded, ""},
 		{"known_failure", func(context.Context, WorkerExecution) (json.RawMessage, error) {
 			return nil, &WorkerFailure{Code: "INPUT_REJECTED", Details: json.RawMessage(`{"field":"name"}`)}
 		}, WorkerFailed, "INPUT_REJECTED"},
 		{"ordinary_error", func(context.Context, WorkerExecution) (json.RawMessage, error) {
 			return nil, errors.New("private error secret")
 		}, WorkerUnknown, "HANDLER_ERROR"},
 		{"panic", func(context.Context, WorkerExecution) (json.RawMessage, error) { panic("private panic secret") }, WorkerUnknown, "HANDLER_PANIC"},
 		{"goexit", func(context.Context, WorkerExecution) (json.RawMessage, error) { runtime.Goexit(); return nil, nil }, WorkerUnknown, "HANDLER_ABORTED"},
 		{"bad_json", func(context.Context, WorkerExecution) (json.RawMessage, error) {
 			return json.RawMessage(`{"n":1,"n":2}`), nil
 		}, WorkerUnknown, "INVALID_HANDLER_RESULT"},
 		{"number_range", func(context.Context, WorkerExecution) (json.RawMessage, error) { return json.RawMessage(`1e999`), nil }, WorkerUnknown, "INVALID_HANDLER_RESULT"},
 	} {
 		t.Run(test.name, func(t *testing.T) {
 			w := &Worker{}
 			w.running.Add(1)
 			done := make(chan handlerCompletion, 1)
 			go w.invoke(context.Background(), WorkerHandler{Handle: test.fn}, WorkerExecution{}, ref, done, make(chan struct{}))
 			select {
 			case got := <-done:
 				if got.result.Outcome != test.out || got.result.ErrorCode != test.code || strings.Contains(string(got.result.Result), "secret") {
 					t.Fatalf("unexpected classification: %s/%s", got.result.Outcome, got.result.ErrorCode)
 				}
 			case <-time.After(time.Second):
 				t.Fatal("handler lost result")
 			}
 			if w.running.Load() != 0 || w.started.Load() != 1 {
 				t.Fatal("handler counters leaked")
 			}
 		})
 	}
 	for _, raw := range []string{`null`, `0.1e-308`, strings.Repeat("[", 31) + "1" + strings.Repeat("]", 31), strings.Repeat("9", 257)} {
 		if validHandlerResult(json.RawMessage(raw)) {
 			t.Fatal("unsupported result passed runtime validation")
 		}
 	}
 }
 func TestWorkerOptionsAndSingleRun(t *testing.T) {
 	c, _ := NewClient("http://127.0.0.1:1", Options{Token: "test-token"})
 	opts := WorkerOptions{QueueID: workerTestQueue, Handlers: []WorkerHandler{{Capability: WorkerCapability{Handler: "test", HandlerVersion: "v1", PayloadVersion: "v1"}, Handle: func(context.Context, WorkerExecution) (json.RawMessage, error) { return json.RawMessage(`{}`), nil }}}}
 	w, err := NewWorker(c, opts)
 	if err != nil {
 		t.Fatal(err)
 	}
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel()
 	if err := w.Run(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if err := w.Run(ctx); !errors.Is(err, ErrWorkerAlreadyRun) {
 		t.Fatal("Worker identity reused after Run")
 	}
 	if _, open := <-w.Events(); open {
 		t.Fatal("event channel not closed")
 	}
 	for _, invalid := range []WorkerOptions{{QueueID: workerTestQueue}, {QueueID: workerTestQueue, Handlers: append(opts.Handlers, opts.Handlers...)}, {QueueID: workerTestQueue, Handlers: opts.Handlers, ShutdownTimeout: -1}} {
 		if _, err := NewWorker(c, invalid); err == nil {
 			t.Fatal("invalid Worker options accepted")
 		}
 	}
 }
 func TestWorkerShutdownBoundsPendingHandshake(t *testing.T) {
 	entered := make(chan struct{})
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { close(entered); <-r.Context().Done() }))
 	defer server.Close()
 	c, _ := NewClient(server.URL, Options{Token: "test-token"})
 	w, err := NewWorker(c, WorkerOptions{QueueID: workerTestQueue, ShutdownTimeout: 50 * time.Millisecond, Handlers: []WorkerHandler{runtimeHandler("test", func(context.Context, WorkerExecution) (json.RawMessage, error) {
 		t.Error("unexpected handler")
 		return nil, nil
 	})}})
 	if err != nil {
 		t.Fatal(err)
 	}
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 	done := make(chan error, 1)
 	go func() { done <- w.Run(ctx) }()
 	select {
 	case <-entered:
 	case <-time.After(time.Second):
 		t.Fatal("handshake did not start")
 	}
 	began := time.Now()
 	cancel()
 	select {
 	case err := <-done:
 		if !errors.Is(err, ErrWorkerShutdownTimeout) {
 			t.Fatal(err)
 		}
 	case <-time.After(time.Second):
 		t.Fatal("shutdown blocked on pending handshake")
 	}
 	if time.Since(began) > 500*time.Millisecond {
 		t.Fatal("handshake exceeded shutdown bound")
 	}
 }
 func TestWorkerPermanentAuthenticationFailureStops(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "private upstream response", http.StatusUnauthorized)
 	}))
 	defer server.Close()
 	c, _ := NewClient(server.URL, Options{Token: "test-token"})
 	w, err := NewWorker(c, WorkerOptions{QueueID: workerTestQueue, Handlers: []WorkerHandler{runtimeHandler("test", func(context.Context, WorkerExecution) (json.RawMessage, error) {
 		t.Error("unauthorized handler invoked")
 		return nil, nil
 	})}})
 	if err != nil {
 		t.Fatal(err)
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
 	defer cancel()
 	err = w.Run(ctx)
 	var stopped *WorkerRunError
 	var status *HTTPError
 	if !errors.As(err, &stopped) || !errors.As(err, &status) || status.StatusCode != 401 || stopped.Unconfirmed != 0 || strings.Contains(err.Error(), "private") {
 		t.Fatalf("unexpected authentication failure: %v", err)
 	}
 }
--- a/sdk/go/worker_runtime_types.go
+++ b/sdk/go/worker_runtime_types.go
@@ -0,0 +1,152 @@
 package orbit
 import (
 	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"sync/atomic"
 	"time"
 )
 var ErrExecutionLeaseLost = errors.New("Worker execution lease expired or lost")
 var ErrWorkerShutdownTimeout = errors.New("Worker shutdown grace period expired")
 var ErrWorkerAlreadyRun = errors.New("Worker instance may only Run once")
 // WorkerExecution 是交给业务处理器的输入，不包含实例或尝试秘密。
 type WorkerExecution struct {
 	Task      Task   // Task 固定任务输入；业务副作用应使用稳定业务身份去重。
 	AttemptID string // AttemptID 当前尝试，用于核查与追踪，不代替业务幂等键。
 	Epoch     uint64 // Epoch 执行代次；接入方资源可用它拒绝旧尝试写入。
 }
 func (e WorkerExecution) String() string {
 	return fmt.Sprintf("WorkerExecution{TaskID:%s AttemptID:%s Epoch:%d data:redacted}", e.Task.ID, e.AttemptID, e.Epoch)
 }
 func (e WorkerExecution) GoString() string { return e.String() }
 // WorkerHandler 注册精确版本的业务函数；函数必须遵守 ctx 的取消。
 // 普通 error/panic 表示效果未知；明确的业务失败返回 *WorkerFailure。
 type WorkerHandler struct {
 	Capability WorkerCapability                                                // Capability 处理器和输入版本，整个 Worker 生命周期固定。
 	Handle     func(context.Context, WorkerExecution) (json.RawMessage, error) // Handle 返回非 null JSON；不得忽略租约取消继续发起副作用。
 }
 // WorkerFailure 仅用于接入方能够确认的业务失败，不用于网络超时或未知外部效果。
 type WorkerFailure struct {
 	Code    string          // Code 1–64 位稳定 ASCII 分类，禁止放原始异常正文。
 	Details json.RawMessage // Details 可选非 null JSON，最多 256 KiB；空值使用空对象。
 }
 func (e *WorkerFailure) Error() string { return "Worker handler reported a known failure" }
 // WorkerOptions 配置自动执行器。一个实例绑定一个队列，只能 Run 一次。
 type WorkerOptions struct {
 	QueueID           string          // QueueID 凭据有消费权限的队列。
 	Capacity          uint32          // Capacity 最大并发处理器数，默认 4，范围 1–256。
 	Handlers          []WorkerHandler // Handlers 1–32 种精确能力，不可重复，函数不得为空。
 	ShutdownTimeout   time.Duration   // ShutdownTimeout 收到 Run context 取消后的收尾总时限，默认 30 秒，最多 5 分钟。
 	ReconnectMinDelay time.Duration   // ReconnectMinDelay 重连退避起点，默认 200 毫秒，至少 10 毫秒。
 	ReconnectMaxDelay time.Duration   // ReconnectMaxDelay 重连退避上限，默认 5 秒，最多 30 秒；采用区间内抖动。
 }
 // WorkerEvent 是有界、可能丢弃的本地观察通知，不是持久化审计或结果订阅。
 type WorkerEvent struct {
 	Type      string // Type connected、reconnecting、handler_started、lease_lost、result_applied、result_evidence、draining。
 	TaskID    string // TaskID 涉及的任务；连接通知为空。
 	AttemptID string // AttemptID 涉及的尝试；连接通知为空。
 	Code      string // Code 稳定错误/结果分类，不包含输入、结果或秘密。
 }
 // WorkerStats 是当前进程的观测值，重启清零，不作为持久化成功率。
 type WorkerStats struct {
 	Running           int64  // Running 尚未返回的处理器数，包含不遵守取消的函数。
 	Started           uint64 // Started 本进程实际调用处理器的次数。
 	RenewalsConfirmed uint64 // RenewalsConfirmed 收到当前续租确认的次数，不代表任务成功。
 	ReportsConfirmed  uint64 // ReportsConfirmed 收到 APPLIED 的结果报告数，包含 UNKNOWN。
 	EvidenceConfirmed uint64 // EvidenceConfirmed 收到 EVIDENCE_ONLY 的报告数。
 	Reconnects        uint64 // Reconnects 首次连接之后发起重连的次数。
 	DroppedEvents     uint64 // DroppedEvents 本地通知缓冲满时丢弃的条数。
 }
 // WorkerRunError 表示执行器未能正常收尾；不能据此认为外部效果已撤销。
 type WorkerRunError struct {
 	Cause       error // Cause 连接/权限/协议错误或收尾超时，支持 errors.Is/As。
 	Unconfirmed int   // Unconfirmed 尚未完成控制核对的已知尝试数。
 	Running     int64 // Running 返回时仍未退出的处理器数；Go 无法强制杀死 goroutine。
 }
 func (e *WorkerRunError) Error() string {
 	return fmt.Sprintf("Worker stopped with %d unconfirmed attempts and %d running handlers: %v", e.Unconfirmed, e.Running, e.Cause)
 }
 func (e *WorkerRunError) Unwrap() error { return e.Cause }
 // Worker 自动管理注册、心跳、续租、重连和有界排空；任务权威状态仍在服务端。
 type Worker struct {
 	client       *Client
 	options      WorkerOptions
 	registration WorkerRegistration
 	handlers     map[WorkerCapability]WorkerHandler
 	used         atomic.Bool
 	events       chan WorkerEvent
 	running      atomic.Int64
 	started      atomic.Uint64
 	renewals     atomic.Uint64
 	reports      atomic.Uint64
 	evidence     atomic.Uint64
 	reconnects   atomic.Uint64
 	dropped      atomic.Uint64
 }
 func NewWorker(client *Client, options WorkerOptions) (*Worker, error) {
 	if client == nil || client.token == "" {
 		return nil, errors.New("authenticated Orbit client is required")
 	}
 	if options.Capacity == 0 {
 		options.Capacity = 4
 	}
 	if options.ShutdownTimeout == 0 {
 		options.ShutdownTimeout = 30 * time.Second
 	}
 	if options.ReconnectMinDelay == 0 {
 		options.ReconnectMinDelay = 200 * time.Millisecond
 	}
 	if options.ReconnectMaxDelay == 0 {
 		options.ReconnectMaxDelay = 5 * time.Second
 	}
 	if options.ShutdownTimeout < time.Millisecond || options.ShutdownTimeout > 5*time.Minute || options.ReconnectMinDelay < 10*time.Millisecond || options.ReconnectMaxDelay < options.ReconnectMinDelay || options.ReconnectMaxDelay > 30*time.Second {
 		return nil, errors.New("invalid Worker shutdown or reconnect duration")
 	}
 	capabilities := make([]WorkerCapability, 0, len(options.Handlers))
 	handlers := make(map[WorkerCapability]WorkerHandler, len(options.Handlers))
 	for _, h := range options.Handlers {
 		if h.Handle == nil {
 			return nil, errors.New("Worker handler function is required")
 		}
 		capabilities = append(capabilities, h.Capability)
 		handlers[h.Capability] = h
 	}
 	r, err := NewWorkerRegistration(options.QueueID, options.Capacity, capabilities)
 	if err != nil {
 		return nil, err
 	}
 	options.Handlers = append([]WorkerHandler(nil), options.Handlers...)
 	return &Worker{client: client, options: options, registration: r, handlers: handlers, events: make(chan WorkerEvent, 128)}, nil
 }
 // Events 返回只读通知流；无需读取也不会阻塞执行，Run 返回时关闭。
 func (w *Worker) Events() <-chan WorkerEvent { return w.events }
 func (w *Worker) Stats() WorkerStats {
 	return WorkerStats{Running: w.running.Load(), Started: w.started.Load(), RenewalsConfirmed: w.renewals.Load(), ReportsConfirmed: w.reports.Load(), EvidenceConfirmed: w.evidence.Load(), Reconnects: w.reconnects.Load(), DroppedEvents: w.dropped.Load()}
 }
 func (w *Worker) emit(event WorkerEvent) {
 	select {
 	case w.events <- event:
 	default:
 		w.dropped.Add(1)
 	}
 }
 func (w *Worker) String() string {
 	return fmt.Sprintf("Worker{QueueID:%s Capacity:%d secrets:redacted}", w.options.QueueID, w.options.Capacity)
 }
 func (w *Worker) GoString() string { return w.String() }