feat: add standalone Worker protocol SDK and ACK-loss regression

docs/sdk/worker.md

@@ -0,0 +1,123 @@
+# Go Worker 底层协议 SDK
+
+更新：2026-09-17。已实现可独立构建的 `WorkerConnection`，配合真实 Orbit 服务和 MySQL 通过控制操作、WSS、ACK 丢失与租约过期回归。**自动 Worker 运行器仍在开发**：本页的方法不会自动启动处理器、心跳、续租、重连或排空。需要持续消费的接入方应等待运行器交付，不能把一次性示例当作完整托管运行时。
+
+源码：[连接与控制方法](../../sdk/go/worker_connection.go)、[中文注释的数据契约](../../sdk/go/worker_types.go)。传输字段、权限和事务语义见 [Worker 接口](../api/worker.md)。SDK 独立 module，只依赖标准库和锁定版本的 `github.com/coder/websocket v1.8.15`，不导入服务端包。
+
+## 1. 可运行的文本规范化示例
+
+需要已完成迁移、已启动的 Orbit 和具有 `workers:connect` / `workers:consume` 权限的专用凭据。在仓库根目录运行：
+
+```sh
+mkdir -p .local
+chmod 700 .local
+go run ./cmd/orbit-admin bootstrap \
+  --application worker-example --namespace default --environment development \
+  --queue normalization --worker-access --output .local/worker.credentials.json
+cd sdk/go
+ORBIT_URL=http://127.0.0.1:8080 \
+  ORBIT_CREDENTIALS_FILE=../../.local/worker.credentials.json \
+  go run ./examples/worker-protocol
+```
+
+预期输出：
+
+```text
+task=<32位任务ID> final_state=SUCCEEDED attempts=1 result={"text":"HELLO ORBIT"}
+```
+
+[完整源码](../../sdk/go/examples/worker-protocol/main.go) 实际提交 `{"text":"  Hello Orbit  "}`，领取并取得开始授权，执行去首尾空格/转大写，报告结果、查询当前状态并排空。没有生成文件或调用外部服务。每次运行创建独立任务与临时处理器名，避免消费前次示例遗留任务；历史和审计保留，不硬删除。
+
+示例最多对开始/结果操作重连重报两次，保持原进程身份、尝试证明、消息 ID 和内容；业务函数只在首次取得有效开始确认后调用一次。网络结果仍不明时非零退出，不能推断服务端回滚。身份与待确认结果只保留在当前进程内，进程被终止后的未知结果由服务端回收进入核查。本示例处理很短的纯计算，不演示长任务自动续租。
+
+## 2. 创建进程身份与连接
+
+以下为接入函数内片段；完整错误处理见示例。
+
+```go
+registration, err := orbit.NewWorkerRegistration(queueID, 4, []orbit.WorkerCapability{
+    {Handler: "text.normalize", HandlerVersion: "v1", PayloadVersion: "v1"},
+})
+if err != nil { return err }
+
+conn, err := client.DialWorker(ctx, registration)
+if err != nil { return err }
+defer conn.Close()
+```
+
+同一进程只生成一次 registration；重连复用，进程重启换新值。它固定凭据、队列、能力集合和实例秘密。不要把身份和秘密复制给另一个活跃进程：新会话会隔离旧会话。
+
+`DialWorker` 的 ctx 只控制握手，最长 8 秒，调用方配置的 HTTP 超时可以更短；成功返回后需主动 Close。URL 基于 `NewClient` 的 HTTP(S) 地址，分别建立 WS/WSS，禁止重定向，不关闭 TLS 证书校验，不把 token 放入 URL。只支持 `pulse.worker.v1` 子协议，禁用压缩。
+
+`Welcome()` 返回首次连接快照；`Done()` 关闭表示读取循环已退出；`Err()` 返回关闭原因。`Close()` 立即停止传输，不撤销外部已发出的请求，也不代替排空确认。
+
+注册和尝试证明包含秘密，JSON 序列化只用于协议。SDK 的 `String` / `GoString` 隐藏注册、尝试、派发和结果中的秘密/业务数据；直接读字段、JSON 日志和调试器仍可能泄露，接入方应只记录任务 ID、尝试 ID 和错误分类。
+
+## 3. 方法清单
+
+除 Welcome/Done/Err/Close，所有连接操作第一个参数都是 context。控制操作同时要求调用方提供 32 位小写十六进制 message ID。
+
+| 方法 | 输入 | 返回 | 注意事项 |
+| --- | --- | --- | --- |
+| `NewWorkerRegistration` | queueID、capacity、capabilities | WorkerRegistration | 生成随机进程身份与秘密，复制/排序能力，拒绝重复能力 |
+| `NewWorkerMessageID` | 无 | string | 只为新的逻辑操作生成；未知结果重报复用旧值 |
+| `client.DialWorker` | registration | *WorkerConnection | 握手后尚未启用派发 |
+| `conn.Capacity` | messageID、WorkerCapacity | WorkerWelcome | 总容量覆盖值；同时续期会话 |
+| `conn.NextAssignment` | ctx | WorkerAssignment | 只表示预占，不能直接运行处理器 |
+| `conn.Start` | messageID、WorkerAttempt | WorkerCommandResult | 持久化开始后确认，检查 Lease 的当前授权 |
+| `conn.Renew` | messageID、WorkerAttempt | WorkerCommandResult | 新续租用新消息；原消息只核对原操作 |
+| `conn.Finish` | messageID、WorkerFinish | WorkerCommandResult | 区分权威结果 APPLIED 与证据 EVIDENCE_ONLY |
+| `conn.Resume` | messageID、WorkerAttempt | WorkerLease | 重连核对原尝试，不创建尝试、不延长租约 |
+
+同连接内 `Capacity.Sequence` 从 1 开始递增；同序号必须同容量/排空标志，不能用增量值。容量为零停止新领取，不释放在途许可。首次确认容量才开启派发，所以重连时可以先 Resume 所有已知尝试，再发布容量。会话与任务续期是两件事：Capacity 不延长任务租约，Renew 不代替会话心跳。
+
+排空使用 `Drain:true`。排空在同进程重连后保留，后续心跳也必须带 true；尝试清除会返回 `STATE_CONFLICT`。排空不禁止收集已发请求结果。
+
+## 4. 当前授权与本地期限
+
+```go
+assignment, err := conn.NextAssignment(ctx)
+if err != nil { return err }
+ref := assignment.Attempt()
+startID, err := orbit.NewWorkerMessageID()
+if err != nil { return err }
+started, err := conn.Start(ctx, startID, ref)
+if err != nil { return err }
+deadline, active := started.Lease.ExecutionDeadline()
+if !active { return errors.New("attempt has no current execution authority") }
+work, cancel := context.WithDeadline(ctx, deadline)
+defer cancel()
+// 将 work 与业务输入传给处理器，不传执行秘密。
+```
+
+`ExecutionDeadline()` 只认可 `Active=true`、`State=RUNNING` 和仍未到期的本地期限。SDK 以服务端 `lease_until-server_time` 为窗口，扣除从调用开始起的全部耗时（含等待写入）及 250 毫秒安全余量，用本地单调时钟表示。数据库墙钟与客户端相差一天也不会额外获得一天授权。
+
+只有 SDK 控制响应会设置内部本地期限；自行构造/JSON 解码的 WorkerLease 不会得到执行授权。旧 start 回执即使包含历史 RUNNING 和未来 lease_until，也不能越过当前 Lease 的失效判断。
+
+此底层接口不会替调用方更新处理器上下文。长任务必须有独立的续租与到期取消机制，断线期间也要在最后确认的本地期限停止推进。新的 Resume/Start 回执不能复活一个已因租约到期而停止的处理器。Go 无法强杀不理会 context 的 goroutine，SDK 更不能撤回外部请求；业务幂等/执行代次隔离仍需在接入方落实。
+
+## 5. 重报与结果分类
+
+| 情况 | 正确处理 |
+| --- | --- |
+| Start 请求结果不明，业务尚未开始 | 保留 startID；重连后 Resume，再用原 startID 核对；核验当前授权后最多开始一次 |
+| 处理器已在当前进程运行，随后断线 | 不再次调用处理器；保留它的已确认租约期限，重连核对原尝试 |
+| Finish 请求结果不明 | 保留原 finishID、Outcome、Result、ErrorCode，重连核对后原样重报 |
+| 明确业务成功 | `WorkerSucceeded`，不带 ErrorCode |
+| 可确认的业务失败 | `WorkerFailed`，带稳定 ErrorCode |
+| 超时、失联或不能确认外部效果 | `WorkerUnknown`，带稳定 ErrorCode，进入核查 |
+| `Disposition=EVIDENCE_ONLY` | 内容已留作证据；不能当作任务成功，另查 GetTask 的权威状态 |
+
+Result 是不超过 256 KiB 的非 null JSON，可传对象引用；原始异常不应写入稳定错误分类。SDK 拒绝非法 Unicode、重复键和过深 JSON，保留数字文本；数值范围仍由服务端最终校验。
+
+## 6. 错误与有界行为
+
+- 握手 HTTP 拒绝返回 `*HTTPError`；业务控制拒绝返回 `*WorkerError`，通过 Code 分支处理。Error() 只显示分类，避免未知错误正文进入日志。
+- 传输中断返回 `ErrWorkerDisconnected`；消息格式/版本不兼容返回 `ErrWorkerProtocol`；主动关闭为 `ErrWorkerClosed`；超时/取消支持标准 context 错误。
+- 最多 32 个在途控制请求，达到上限返回 `ErrWorkerBusy`，请求未发送。同一消息 ID 已在途时也拒绝第二个并发等待者。
+- 派发缓冲最多 8 条；读取不及时会以 `ErrWorkerBackpressure` 关闭连接。持久化预占由服务端恢复，不无限积压内存。
+- 控制操作最长 10 秒，包含排队、发送与等待 ACK；调用方 context 可以缩短。已发送后取消/超时会关闭连接，操作是否提交需用原身份核对。
+- `NextAssignment` 的 context 取消只停止等待，不关闭连接。已关闭连接不会继续交付缓冲中的派发。
+- 入站单帧最多 512 KiB；读空闲期限 60 秒。需要调用方持续心跳，不能用此期限代替默认 45 秒会话期限。
+
+以上是实现上限与正确性保护，不是容量承诺。测试命令与真实覆盖见 [P2 SDK 协议回归](../reports/phase-2-sdk-protocol.md)。