feat: establish Orbit models, migrations and development baseline

2026-09-17 07:04:21 +08:00
commit 4f2935e36f
84 changed files with 4915 additions and 0 deletions
--- a/docs/01-functional-spec.md
+++ b/docs/01-functional-spec.md
@@ -0,0 +1,135 @@
+# Orbit 功能说明：Pulse 与公共能力
+
+> 版本 0.2 · 2026-09-17。Pulse 与 Weave 首版功能范围已确认；标注“建议”的细节待评审。Weave 具体范围另见流程设计。基础骨架已实现，任务业务能力仍待开发；实现状态见持续开发计划。
+
+## 1. 目标与责任边界
+
+Orbit 统一提供任务调度与流程编排。Pulse 接收一个明确的工作单元，按照时间、容量、权限和重试策略交给业务 Worker 执行，管理可查询、可恢复的执行过程。Weave 将多个工作单元按流程规则连接起来，具体方案见 [流程设计](06-workflow-spec.md)。
+
+| 参与方 | 职责 |
+| --- | --- |
+| Pulse | 任务受理、调度、派发、执行权、重试控制、运行记录、结果交付 |
+| 业务系统 / Worker | 业务校验、业务授权、外部调用、业务幂等、业务结果与证据 |
+| Weave（内部模块） | 研发定义发布、多步骤依赖、分支、汇合、持久化等待、有界重复查询、暂停/继续、人工恢复与流程版本 |
+| MySQL 运维 | 数据持久化与复制配置、备份、故障切换、恢复演练 |
+
+任务可以是一次文件转换、一次数据准备或一次外部作业结果查询。Pulse 管理任务执行过程，具体业务结果和完成条件由处理器契约定义。
+
+任务类型、参数和标识采用通用模型，不要求平台理解接入方的专用业务概念。
+
+## 2. 基本概念
+
+| 概念 | 含义 |
+| --- | --- |
+| 应用 / 环境 / 命名空间 | 接入身份与资源边界；建议一个应用环境对应一个命名空间 |
+| 队列 | 任务路由、资源配置与 Worker 消费范围 |
+| 任务类型与版本 | 处理器身份及其兼容版本 |
+| 任务 | 一项已受理工作，具有稳定的任务 ID |
+| 执行尝试 | 一次派发与执行过程，具有独立尝试 ID 和执行凭据 |
+| 调度计划 | 产生任务的时间规则，每次实际触发产生独立任务 |
+| 业务关联键 | 由业务方提供的查找、追踪标识 |
+| 并发控制键 | 在规定作用域内限制同时有效执行许可的通用标识 |
+
+自动重试沿用任务 ID，产生新的执行尝试。HTTP 请求重试、任务重试和定时计划的下一次触发是三件不同的事情。
+
+Weave 有界查询的一轮对应一个 Pulse 任务；查询得到“处理中”后，Weave 等待并创建下一轮任务。当前轮请求失败由 Pulse 在原任务下重试，不能通过开启新轮次绕过重试上限。
+
+## 3. 任务提交与管理
+
+### 3.1 提交方式
+
+- **立即执行**：受理后尽快进入可派发范围，实际开始时间受资源和排队影响。
+- **延迟执行**：在指定等待时长之后才允许开始。
+- **指定时间执行**：在指定时间之后才允许开始，不承诺硬实时触发。
+- **批量提交**：多项普通任务的提交方式；建议逐项返回结果，每项独立幂等，失败项独立补交。
+
+任务至少说明：归属、队列、处理器与版本、参数版本、执行时间、时限、重试规则和提交幂等标识。已受理参数与生效策略保存快照；修改配置不静默改写历史任务。
+
+最晚允许开始时间、单次执行超时、任务总时限分别定义。到期后停止授权新的执行；已经发出的业务请求是否产生效果，需要按处理器的结果确认规则判断。
+
+### 3.2 操作行为
+
+| 操作 | 目标行为 |
+| --- | --- |
+| 幂等提交 | 同作用域、同标识、同语义请求返回原任务；同标识不同请求明确冲突 |
+| 查询 | 返回当前任务状态、关联计划、执行尝试、错误与结果引用 |
+| 取消待执行任务 | 在与开始执行的竞争中原子决定取消是否生效 |
+| 取消执行中任务 | 持久化取消意图并通知 Worker，等待停止或最终结果，已有业务效果不自动撤销 |
+| 人工重试 | 校验权限、错误类别及业务确认条件，保留原历史，记录操作人和原因 |
+| 修改业务参数 | 新建关联任务，原任务参数不变 |
+
+**设计建议：人工重试创建带 `retry_of` 的新任务。** 原任务保留终态及结果，避免外部订阅方已经消费终态后任务又悄悄恢复。业务幂等键应按原操作语义保留；平台新任务 ID 不代表允许重复产生业务副作用。此项在协议冻结前确认。
+
+流程关联任务的人工恢复统一经过 Weave，校验流程版本、步骤归属和当前恢复条件；不能直接从普通任务重试入口生成无人接续的流程任务。
+
+流程暂停的门控建议由 Pulse 通用执行控制承载，阻止关联任务的新领取、开始和执行重试，同时继续收集已授权执行的结果。它与定时计划暂停、队列暂停分别建模；具体规则见 [Weave 暂停与继续](06-workflow-spec.md#71-暂停与继续)。
+
+任务成功表示处理器完成约定的这一步。例如“渠道提交已受理”可以是一个处理器的成功结果，最终业务成功应由查询或回执处理任务另行确认。
+
+## 4. 定时计划
+
+- 支持 Cron、固定间隔、时区、生效与结束边界、启用、暂停、恢复和修改计划。
+- **设计建议**：首版采用五段 Cron；固定间隔首先定义为按基准时间推进的 fixed-rate。是否增加“完成后再等待”的 fixed-delay 待确认。
+- 每个实际触发点具有唯一身份，记录采用的计划版本与原计划时间。
+- 计划变更明确生效边界；已生成任务保留原参数与策略快照。
+- 暂停计划阻止新的触发，不隐式取消已经生成或正在执行的任务。
+
+创建计划时必须明确以下策略，不能在故障后临时猜测：
+
+| 情况 | 可选策略及限制 |
+| --- | --- |
+| 漏跑 | 跳过、合并为一次、按次补跑；补跑必须有数量/时间窗口与速率上限 |
+| 上一轮未完成 | 允许并行、串行等待、跳过本次；串行等待也必须有积压上限 |
+| 时区夏令时变化 | 明确不存在时刻、重复时刻的处理，首版选定并测试后发布 |
+| 停机期间修改计划 | 保存版本与生效边界，按明确的历史版本计算漏跑 |
+
+跳过和合并需留下原因、原计划时间或覆盖范围。业务日历由业务系统决定，Pulse 执行其提交的时间计划。
+
+## 5. Worker 与执行恢复
+
+- Worker 通过 WSS 主动连接，经过鉴权后声明处理器版本、消费队列及执行容量。
+- SDK 封装消息收发、任务去重、租约续期、结果重报、带抖动的重连和优雅退出。
+- 同一 Worker 可执行多个任务，网络读写不能被业务处理器阻塞。
+- 任务只分配给版本兼容且有容量的 Worker；无兼容 Worker 时可观测地等待，并受时限约束。
+- 连接心跳检测通信；任务续租确认具体执行权，两者独立。
+- 断线后先核对任务，不直接认定业务失败；无有效租约时 Worker 应停止推进并尝试取消可取消的操作。
+- 优雅退出时停止接新任务，给已有任务留出受控完成时间，退出超时按恢复规则处理。
+
+错误至少区分：可安全重试、明确不可重试、需要外部核查、需要人工处理。策略包含退避、抖动、尝试上限或总时限，禁止无限快速重试。
+
+副作用是否发生不明确时，不允许因为“网络错误”自动重复提交业务操作。任务类型必须声明恢复安全等级；声明缺失时采用保守处理。
+
+## 6. 队列与资源控制
+
+- 支持队列并发、应用配额、速率限制、优先级和项目间公平性。
+- 支持按业务提供的并发控制键限制有效执行许可。例如可用资源标识限制同一资源的一类操作。
+- 跨节点限制必须由共享状态协调，单节点内存计数只能约束该节点。
+- 并发控制不自动提供跨任务严格顺序；需要顺序的业务必须明确顺序协议或交由流程编排。
+- 任务数量、参数大小、发送缓冲、事件积压和重试均有有限上限，并提供拒绝/背压行为。
+
+过期 Worker 仍可能在物理上运行。业务资源端还需幂等或执行代次校验，避免旧执行产生额外效果。
+
+## 7. 多项目、安全与管理
+
+支持应用与环境隔离、可轮换凭据、队列级提交和消费授权、查询权限与管理权限。命名空间和 Worker 标识不能替代身份认证。
+
+管理操作包括暂停队列派发、调整配额、取消、人工重试和计划变更。都应记录操作人、时间、原因和前后状态。暂停派发不等于强制停止运行中的处理器。
+
+参数、结果与日志设置访问控制和脱敏规则。大文件使用业务侧引用；凭据不作为普通任务参数或日志传递。
+
+## 8. 查询、审计、告警与结果交付
+
+- 通过任务 ID、业务关联键、状态、队列、时间范围查找任务。
+- 保存执行尝试和关键状态转换，关联 Worker、版本、错误分类与结果引用。
+- 监控任务积压、到期派发延迟、重试、失联、数据库异常、结果通知积压和资源用量。
+- 提供可靠结果订阅：事件持久化，接收方处理后确认，未确认可再次交付。
+- 运行统计可最终一致；影响派发与终态判断的状态必须按权威状态读取。
+- Orbit 运行审计与业务审计通过关联标识衔接，保存策略分别制定。
+
+## 9. 首版范围与后续扩展
+
+上述生产相关行为属于首版设计范围。首版首先交付 Go SDK、管理 API 与必要运行指标。完整图形化控制台、其他语言 SDK、高级全文检索及跨地域主动写入作为后续扩展评估。
+
+流程依赖、等待及有界查询由平台内的 Weave 承担，已确认范围见 [流程功能与设计](06-workflow-spec.md)。审批人员与业务权限规则、专用规则计算由业务系统承担。通用 SQL 查询平台、文件处理平台不纳入 Orbit。
+
+功能是否达标以 [生产验收](05-production-acceptance.md) 的结果为依据，不以接口存在或演示运行成功代替。
--- a/docs/02-technical-design.md
+++ b/docs/02-technical-design.md
@@ -0,0 +1,143 @@
+# Orbit 技术方案
+
+> 版本 0.2 · 2026-09-17。Orbit 统一项目内保留 Pulse 与 Weave 两个模块。本文描述总体技术方案；基础部分已实施，执行引擎尚未完成。
+
+## 1. 技术基线
+
+| 项目 | 决策或建议 |
+| --- | --- |
+| 项目形态 | Orbit 通用平台，Pulse 负责任务与时间调度，Weave 负责流程编排 |
+| 语言 | 当前基础使用 Go 1.27.1 |
+| 接入 | HTTP + WebSocket，JSON；生产使用 HTTPS / WSS |
+| 存储 | MySQL 8.4+，保存两个模块的权威状态；生产高可用拓扑待实际部署验收 |
+| 服务端结构 | 核心应用逻辑独立于 HTTP / WS 适配层；建议显式依赖装配 |
+| 数据访问 | 当前采用显式 SQL、普通 Go 模型、短事务；未引入 ORM |
+| SDK | 首版 Go SDK，统一连接配置与鉴权，分别暴露任务与流程能力 |
+| 必需外部组件 | MySQL；首版运行不依赖独立 Redis、消息队列或协调服务 |
+| 运维输出 | 结构化日志、健康接口、指标与追踪接口；可接入既有监控系统 |
+
+基础实现已选择 MySQL 8.4+，本轮在 8.4.10 测试。HTTP 与 WS 可复用成熟 Go 库；基础库被编译进程序不构成新增独立中间件服务。
+
+## 2. 模块边界
+
+| 模块 | 拥有的数据与行为 |
+| --- | --- |
+| 公共接入与治理 | 身份、环境、权限、协议、限额、公共审计与可观测接口 |
+| Pulse | 任务、尝试、租约、队列额度、定时计划、执行结果和任务恢复 |
+| Weave | 流程定义与版本、实例、步骤、分支、等待、信号、查询轮次、暂停与流程恢复 |
+
+Weave 通过 Pulse 的应用层接口创建或取消任务。Pulse 的任务内核只保存通用关联信息，不理解行业业务或特定流程图。
+
+两个模块可以共享一次事务，但不能任意直接修改对方的表。由应用服务显式传递事务上下文，在各自模块内完成约束校验。公共事务协调代码不应演变为包含所有业务规则的大对象。
+
+执行一次任务的自动重试由 Pulse 管理；Weave 根据步骤最终结果决定下一步、等待处理或结束。Weave 不为同一执行失败再偷偷启动一套叠加重试循环。
+
+当前 `pulse/model/` 与 `weave/model/` 已包含模型，服务入口、SDK 与迁移结构见 [数据模型基线](07-data-model.md)。执行引擎与业务接口按开发计划推进，模块边界通过接口与数据所有权保持。
+
+## 3. 运行结构
+
+```mermaid
+flowchart LR
+    B[业务系统] -->|HTTPS 提交与管理| H[HTTP 接入]
+    W[业务 Worker / SDK] <-->|WSS 双向通信| G[WS 会话网关]
+    H --> P[Pulse 任务与调度]
+    H --> F[Weave 流程编排]
+    F -->|模块接口创建步骤任务| P
+    G --> P
+    P --> D[(MySQL 权威状态)]
+    F --> D
+    D --> R[恢复与内部事件处理]
+    R --> P
+    R --> F
+```
+
+首版建议同一个服务程序包含 HTTP、WS、调度、派发、恢复、流程推进及事件交付等角色，多实例运行。配置预留角色启停，后续可按负载拆运行进程；拆进程不要求先拆仓库或协议体系。
+
+业务处理器留在 接入方业务项目的 Worker 中。平台内部定时唤醒等内置处理器仍需遵守任务状态、幂等和资源边界，不通过直接改业务状态绕过机制。
+
+## 4. 数据与内存的分工
+
+- MySQL 保存权威任务状态、授权租约、流程检查点、计划进度、幂等与待交付事件。
+- 内存保存 WS 连接、候选任务引用、近期时间索引及可重建的统计。
+- 内存唤醒只减少等待；遗漏唤醒必须能通过有界、索引化的数据库检查恢复。
+- 领取、续租、完成及流程推进等决策访问权威写入节点；不能基于滞后的只读副本授予执行权。
+- 关键状态落库后才确认成功。仅把日志写入数据库、把执行事实长期留在内存，不满足该设计。
+
+MySQL 的事务与行锁提供并发更新基础，但任务状态机和幂等语义仍由平台实现。[MySQL 事务模型](https://dev.mysql.com/doc/refman/8.4/en/innodb-transaction-model.html)
+
+## 5. 多实例派发与 WS 归属
+
+每个 Worker 的连接由当前接入节点管理。该节点根据本地连接的授权队列、兼容版本与容量，按需领取任务并持久化分配，然后通过本地连接发送。
+
+提交请求可能进入 A 节点，而可执行 Worker 连接在 B 节点。B 通过共享 MySQL 中的待执行记录发现任务；首版不要求另设消息总线来转发节点间通知。
+
+领取采用有界批次、明确索引与短事务，可评估 `SKIP LOCKED` 或条件更新。发送 WS 消息、等待确认与执行业务均在事务之外。
+
+数据库检查由平台按活跃队列/分区统一调度，不能为每一个空闲连接都启动高频数据库扫描。跨节点发现延迟进入调度延迟指标，不能宣称 WS 消除了数据库轮询。
+
+节点失效后 Worker 重连其他节点，先依据 MySQL 核对会话与租约，再续接或停止旧尝试；不依赖负载均衡的粘性会话保证正确性。
+
+## 6. 定时与流程推进
+
+Pulse 扫描有索引的到期计划或任务，受控地产生可执行工作。近期时间索引可以缓存在内存，进程重启后按计划进度重建。
+
+Weave 与 Pulse 同库时利用两个明确的事务边界：
+
+1. **步骤任务创建事务**：更新流程/步骤状态，并通过 Pulse 接口创建下一步任务，一起提交。
+2. **任务结果接续**：Pulse 保存终态时同时保存内部结果事件；Weave 可异步消费该事件，在一个新事务内更新步骤、推进流程、创建后续任务并标记事件已处理。
+
+此处不需要跨服务 RPC 或外置 MQ。事件仍必须持久化并可去重，防止进程在任务完成后、流程推进前宕机造成停滞。
+
+Weave 的信号、等待、有界查询、暂停、取消和人工恢复细节见 [流程设计](06-workflow-spec.md)。进入待核查状态也必须产生内部状态事件，不能只有任务终态才能让流程感知异常。
+
+有界查询通过“查询任务 → 保存处理中结果 → 持久化等待 → 下一轮任务”推进。轮次与任务创建原子提交，单轮请求的自动重试仍归 Pulse；等待不占用业务 Worker。查询总时限、轮次数与单轮尝试组合都有限制。
+
+暂停建议通过共享事务更新流程控制版本和 Pulse 的通用执行门控；业务任务领取、开始及后续尝试必须校验门控。控制门限与领取竞争采用一致的锁定/版本协议，单次读取后脱离事务决定开始不满足要求。Pulse 不需要读取流程图或理解业务含义。已授权执行、内部结果收集与到期记录继续进行，恢复所需推进记录必须持久化。
+
+流程定义和分支计算不能在长数据库事务里等待外部调用。一次推进设工作量上限；大规模并行展开分批持久化，使用检查点恢复。
+
+## 7. 并发、限流与扩展
+
+- 根据队列或稳定路由键建立逻辑分区；队列数与租户数分开，不能默认一个租户创建一个平台队列或一条连接。
+- 使用短事务协调跨节点的有效并发额度和同业务键执行许可，明确获取与释放顺序。
+- 一条连接慢或一个应用积压时，通过有界缓冲、配额与公平调度控制影响。
+- 心跳续租可按批发送，但逐项校验身份；批量减少通信或事务开销，不取消可靠持久化要求。
+- 活跃状态和长期历史分开组织，归档、扫描及补跑都有资源预算。
+- 先通过基准与故障测试验证容量，再决定物理分库。物理分片前需明确流程与步骤任务的同事务路由范围。
+
+首版不承诺全局 FIFO、跨地域多活写入或无限队列容量。严格顺序应通过明确的业务序号与流程依赖表达，不能从 WS 单连接传输顺序推导出来。
+
+## 8. SDK 与业务接入
+
+建议 SDK 独立 Go module，避免把服务端 SQL、迁移和存储依赖带入业务项目。服务端实现和 SDK 使用同一份协议规范。
+
+目标 SDK 能力包括：任务/流程客户端、Worker 运行组件、连接恢复、执行上下文、结果确认、追踪传播，以及可选的业务 Outbox 适配层。
+
+已确认由研发通过 Go SDK 描述并发布流程。建议 SDK 生成版本化 JSON 定义，服务端校验并保存不可变版本；流程发布与实例启动是独立操作。定义构建 API 不上传业务闭包或要求 Orbit 执行业务 Go 源码，完整接口形式仍待评审。
+
+业务处理器接收任务身份、参数、取消上下文及当前执行信息。接入文档必须解释副作用幂等、结果未知、续租失败与停止行为，不能让 SDK 的自动重试掩盖这些责任。
+
+## 9. 生产部署与数据安全
+
+建议至少部署两个平台实例用于应用层故障接管，放在适当的故障域。MySQL 必须采用明确的高可用与备份方案；其具体拓扑和数据确认语义单独验收。
+
+MySQL 的 InnoDB Cluster 等成熟方案可以提供复制与故障切换，但配置、维护与恢复责任仍需要落实。[MySQL 高可用说明](https://dev.mysql.com/doc/refman/8.4/en/mysql-innodb-cluster-introduction.html)
+
+数据库不可用时，停止新的受理确认、执行授权与流程状态推进；续租未确认的 Worker 按已确认租约边界处理。不能切换到只有内存确认的临时模式。
+
+发布需排空连接、保留兼容的旧处理器版本、按步骤迁移数据库；禁止多实例启动时无协调地自动修改表结构。备份恢复需要核对已经发生的外部业务效果。
+
+具体容量、消息大小、扫描周期、心跳、租约、连接上限与恢复时限由 [生产验收](05-production-acceptance.md) 给出测试证据后确定。
+
+## 10. 工程规范建议
+
+以下作为实施前的工程基线草案，与具体框架、路由库的选择分开讨论：
+
+- **依赖方向**：协议适配层调用应用服务，应用服务协调领域规则与存储接口；核心状态机不依赖 HTTP / WS 对象。Pulse 不反向依赖 Weave 的流程规则，公共包不得包含接入方的专用业务逻辑。
+- **并发与生命周期**：后台循环、连接读写、处理器均有明确的创建与退出归属；通过上下文传播取消与时限，限制 goroutine、缓冲及数据库连接数量。捕获处理器 panic 后按副作用安全等级处理，不能默认重跑。
+- **错误契约**：区分协议错误、权限错误、状态冲突、临时基础设施错误、业务失败与结果未知。错误码保持兼容，日志保留内部原因，对外响应不泄露 SQL、密钥或敏感参数。
+- **配置**：启动校验租约、续租、超时、容量与保留期限之间的约束；动态配置有版本、审计和明确生效范围。密钥独立管理，不放入仓库或普通配置快照。
+- **数据库演进**：迁移脚本版本化，通过受控单一执行入口应用；滚动升级先做兼容性扩展，再迁移数据和收缩旧结构。数据修复使用可审计操作流程。
+- **可观测性**：任务、尝试、流程、步骤与请求 ID 用于日志和追踪关联；租户 ID、任务 ID 等无界值不作为常规指标标签。审计事件与调试日志分别保留。
+- **质量检查**：建立格式、静态检查、适用的 Go 竞态检测、协议兼容和迁移检查；使用真实 MySQL 验证事务、锁竞争与恢复，不能仅依靠存储 Mock 得出并发正确性结论。
+- **发布与接入**：服务端、SDK 与处理器维护独立版本和兼容矩阵；变更给出升级顺序与迁移说明。业务接入验收覆盖幂等、未知结果、取消和恢复，不能仅以 SDK 调用成功作为完成标准。
--- a/docs/03-http-websocket-protocol.md
+++ b/docs/03-http-websocket-protocol.md
@@ -0,0 +1,178 @@
+# Orbit HTTP 与 WebSocket 协议草案
+
+> 版本 0.2 · 2026-09-17。HTTP + WS 已确认。本文的具体路径、消息名、字段及状态码是首版设计建议，业务协议尚未实现，需评审后冻结；健康接口的已实现契约见接口手册。
+
+## 1. 通用契约
+
+- 生产使用 HTTPS / WSS；HTTP 承担任务提交、流程启动与信号、查询、管理，WS 承担 Worker 双向通信与结果订阅。
+- 数据采用 JSON；HTTP 契约使用 OpenAPI 描述，WS 消息使用版本化 JSON Schema 与交互时序描述。
+- ID 与执行代次等可能超出跨语言整数精度的值使用字符串。时间使用 RFC 3339 UTC 字符串，时长字段注明单位。
+- 请求体、消息、批量条数、查询页大小和发送缓冲都必须有限制；具体上限见待定参数表。
+- 鉴权后校验应用、环境、队列和操作权限。请求中的命名空间、Worker ID、任务 ID 不能代替授权。
+- SDK 与服务端维护兼容矩阵；不兼容的协议或处理器版本明确拒绝，不静默解释为当前版本。
+
+## 2. HTTP 接口草案
+
+| 方法与路径 | 行为 |
+| --- | --- |
+| `POST /v1/tasks` | 幂等提交一项任务 |
+| `POST /v1/tasks:batchSubmit` | 批量逐项提交，每项独立幂等 |
+| `GET /v1/tasks/{task_id}` | 查询权威任务状态与结果摘要 |
+| `GET /v1/tasks/{task_id}/attempts` | 分页查询执行尝试 |
+| `GET /v1/tasks` | 按有索引的字段分页查询，支持提交幂等键精确查找 |
+| `POST /v1/tasks/{task_id}:cancel` | 请求取消，记录原因 |
+| `POST /v1/tasks/{task_id}:retry` | 普通任务人工重试；流程关联任务须经 Weave 恢复入口 |
+| `POST /v1/schedules` | 创建计划，明确漏跑和重叠策略 |
+| `PATCH /v1/schedules/{schedule_id}` | 带预期版本修改计划，冲突时拒绝覆盖 |
+| `POST /v1/schedules/{schedule_id}:pause` | 暂停计划的新触发 |
+| `POST /v1/schedules/{schedule_id}:resume` | 按漏跑策略恢复计划 |
+| `GET /v1/schedules/{schedule_id}/occurrences` | 查询计划触发记录 |
+| `GET /health/live`、`GET /health/ready` | 进程存活与接单就绪状态，二者独立 |
+
+应用、凭据、队列、配额和审计管理接口沿用同一鉴权、版本与错误规范，其完整路径清单在接口评审时补齐。就绪检查必须反映关键依赖，数据库不可用时不能继续宣称可安全接单。
+
+Weave 的补充接口建议如下，功能范围已确认，具体技术细则以 [流程设计](06-workflow-spec.md) 为准：
+
+| 方法与路径 | 行为 |
+| --- | --- |
+| `POST /v1/workflow-definitions/{definition_id}/versions` | 研发通过 SDK 发布不可变定义；同版本同内容幂等，不同内容冲突 |
+| `POST /v1/workflows` | 幂等启动流程，固定定义版本 |
+| `GET /v1/workflows/{workflow_id}` | 查询实例、定义版本、执行状态、暂停标记与等待摘要 |
+| `GET /v1/workflows/{workflow_id}/steps` | 分页查询步骤、输入/结果引用、激活、查询轮次、已用预算与关联任务 |
+| `POST /v1/workflows/{workflow_id}/signals` | 幂等受理信号，不等于信号已经被消费 |
+| `GET /v1/workflows/{workflow_id}/signals/{signal_id}` | 查询信号受理、匹配与消费结果 |
+| `POST /v1/workflows/{workflow_id}:pause` | 持久化暂停门控与审计；不代表在途业务已停止 |
+| `POST /v1/workflows/{workflow_id}:resume` | 解除暂停并安排受控推进；不重置预算、核查状态或原版本 |
+| `POST /v1/workflows/{workflow_id}:cancel` | 记录取消意图，结清关联工作 |
+
+流程列表、事件查询与人工核查/恢复接口待细化；恢复必须带预期状态版本、稳定操作身份、原因与证据，不提供任意修改状态的通用入口。
+
+暂停和继续使用独立管理权限、预期控制版本、幂等操作身份与原因；同一操作重报返回原确认，过期控制版本不能覆盖后来的操作。建议 `200` 确认门控已提交，后续执行进度通过查询观察；门控失效条件和终态操作错误在协议评审时固定。
+
+### 2.1 受理、幂等与错误
+
+- 首次创建任务、流程或信号记录的建议响应为 `201 Created`，表示资源及幂等记录已可靠提交，不表示业务执行或信号消费完成。
+- 相同幂等请求返回 `200` 和原资源 ID，标记 `deduplicated: true`；相同键不同语义请求返回 `409`。
+- 单项提交使用 `Idempotency-Key`；批量每项使用 `submission_key`，由 SDK 统一映射为提交幂等标识。
+- 普通任务提交幂等作用域为命名空间内的任务提交操作；流程启动使用独立操作作用域，信号按命名空间、实例与信号 ID 去重。其他管理写操作按命名空间、操作和资源界定作用域，避免同一个键在不同 API 间意外冲突。
+- HTTP `request_id` 仅用于追踪，与业务幂等键分开。
+- 请求超时后，使用原幂等键查询或重试；不能通过换一个键来猜测原请求是否失败。
+- 语义哈希排除请求追踪、连接身份等传输字段，明确 JSON 规范化、缺省值和数组顺序；不能依赖普通 map 的序列化顺序。算法在协议冻结时确定。
+
+建议统一响应结构：成功包含 `request_id` 和 `data`；失败包含 `request_id` 和 `error`，其中 `error` 含稳定的 `code`、可读 `message` 和受控的 `details`。
+
+| HTTP 状态 | 用途 |
+| --- | --- |
+| 200 / 201 | 查询或已确认的操作结果 / 新资源可靠创建 |
+| 202 | 取消等操作已记录意图，最终行为仍在推进 |
+| 400 / 422 | 协议格式错误 / 语义校验失败 |
+| 401 / 403 | 未认证 / 无操作权限 |
+| 404 | 不存在或按访问策略隐藏的资源 |
+| 409 | 幂等内容冲突、资源版本冲突或操作状态冲突 |
+| 429 / 503 | 容量限制 / 服务暂不可用，可提供 `Retry-After` |
+
+批量请求顶层校验通过后可返回 `200`，但每项必须给出索引、任务 ID 或错误。顶层成功不表示每项均被受理。限流或断线后的补交仍使用原逐项幂等键。
+
+## 3. Worker 连接
+
+建议入口：`GET /v1/worker/connect`，使用 WebSocket Upgrade，协商子协议 `pulse.worker.v1`。SDK 在握手中携带应用凭据，不把长期密钥放在 URL 查询参数中。
+
+连接生命周期：鉴权 → 协议协商 → 能力登记 → 恢复核对 → 可接单 → 排空 / 断线。
+
+- `worker_instance_id` 标识一个进程实例，重连保留，重启建议新建；可另设可读名称。
+- `session_id` 标识本次连接。新连接需有新的会话身份，旧连接消息不得继续修改新会话的执行权。
+- 恢复执行必须校验认证身份、执行凭据和数据库中的当前归属，不能仅凭相同 Worker 名称认领。
+- Worker 声明队列、处理器兼容版本及容量。平台授权与配额优先于客户端声明。
+
+## 4. 消息信封
+
+以下为示意，时间与数值不是生产默认参数：
+
+```json
+{
+  "protocol_version": "1",
+  "type": "task.assign",
+  "message_id": "msg_example",
+  "session_id": "session_example",
+  "task_id": "task_example",
+  "attempt_id": "attempt_example",
+  "body": {
+    "handler": "report.generate",
+    "handler_version": "1",
+    "payload_version": "1",
+    "payload": {"report_ref": "report_example"},
+    "lease_token": "example-only-not-a-real-secret",
+    "lease_expires_at": "2026-09-17T08:00:30Z"
+  }
+}
+```
+
+响应通过 `reply_to` 关联原消息。需要可靠确认的操作使用稳定消息 ID；跨重连重报时保留操作身份，但使用当前会话认证。传输会话变化不改变操作的语义哈希。
+
+执行凭据属于敏感信息，不进入普通日志、管理查询或指标标签。Task / Attempt / Message / Session 四种 ID 分别表达业务工作、执行尝试、通信操作和连接。
+
+## 5. 消息类型与确认
+
+| 消息 | 方向 | 语义 |
+| --- | --- | --- |
+| `worker.hello` / `worker.welcome` | 双向 | 协商能力、版本、会话与协议限制 |
+| `worker.resume` / `worker.resume.result` | 双向 | 核对断线前的执行尝试，逐项给出续接、停止或核查结果 |
+| `worker.capacity` | Worker → 平台 | 更新容量声明；带会话内序号，重复上报不得重复增加额度 |
+| `task.assign` | 平台 → Worker | 派发已持久化授权的任务与执行凭据 |
+| `task.start` | Worker → 平台 | 确认接单并申请开始；建议获平台确认后再调用处理器 |
+| `task.renew` | Worker → 平台 | 续期有效执行租约，可批量但逐项确认 |
+| `task.complete` | Worker → 平台 | 提交结果或结果引用，等待持久化确认 |
+| `task.fail` | Worker → 平台 | 提交错误分类及已知业务结果，平台按冻结策略决定后续行为 |
+| `task.cancel` | 平台 → Worker | 传递已保存的取消意图，不代表副作用被撤销 |
+| `task.cancelled` | Worker → 平台 | 报告处理器停止及已知效果；未知效果转核查，不自动成为取消终态 |
+| `worker.drain` | 双向 | 停止接收新任务，受控完成已有任务 |
+| `ack` / `error` | 双向 | 关联明确操作的确认或错误，不能用连接 Pong 替代 |
+
+建议采用两步派发：平台先保存 `LEASED` 并发送任务；Worker 发 `task.start`，平台原子确认有效租约和未被取消后保存 `RUNNING`，再确认执行。消息丢失时按同一尝试重报或核对，不能未经重新授权自行执行。
+
+如关联执行门控已暂停，尚未获开始授权的 `task.start` 不能被确认可执行；已确认开始的操作重报只补取原确认，不授予第二次执行。具体暂挂、释放预占容量和恢复派发的消息细节在协议冻结时补齐。
+
+`RUNNING` 表示平台已授权开始，不足以证明业务侧已经发生某项效果。租约前后派发与取消的竞争见 [可靠性模型](04-reliability-and-data.md)。
+
+### 5.1 完成确认丢失
+
+1. 平台在同一事务内保存任务终态、尝试结果与待交付事件。
+2. 提交成功后回复 `ack`。
+3. SDK 未收到确认时，重报相同结果或查询任务。
+4. 已确认的同一尝试、同一结果再次上报，返回原确认，即使此时原租约已经到期。
+5. 不同结果冲突或过期尝试试图写入新结果时拒绝修改，保留可诊断记录。
+
+先验证权限，再识别已完成操作的幂等重报，最后对新操作校验租约，避免将合法的确认补取误判为任务失败。
+
+SDK 可以在进程存活期间缓存未确认消息；不得宣称内存缓存能跨进程崩溃恢复。业务效果已发生但结果尚未回报的情况，依赖业务幂等、业务侧操作记录或结果查询恢复。
+
+## 6. 心跳、重连与背压
+
+- Ping/Pong 用于连接活性；具体任务的续租必须单独经过授权与持久化确认。[WebSocket 标准](https://www.rfc-editor.org/rfc/rfc6455.html#section-5.5.2)
+- 任务续租失败后，SDK 不能仅因连接仍在线就继续假定执行权有效。
+- SDK 根据服务端确认的租约期限，结合请求耗时、安全余量及本地单调时钟管理停止边界；不直接信任客户端墙上时钟与服务器完全一致。
+- 重连使用有上限的指数退避与抖动；支持凭据刷新、重新鉴权和恢复核对。
+- 断线后允许在最后确认的有效租约内按策略推进；无法及时恢复有效执行权时，停止推进并尽力取消可取消操作。外部已发请求仍需核查。
+- 重连可进入任一平台节点；有效旧尝试经原子校验迁移到新会话，失效尝试不得因重连复活。
+- 平台为已派发未确认的任务预占容量。容量消息采用序号和明确的覆盖/计算规则，重复消息不能释放或重复发放额度。
+- 单连接读写由独立循环管理；设置消息上限、读写期限和有界发送队列，处理器运行不占网络循环。
+- 慢消费者停止追加派发；非关键进度更新可合并，关键状态与结果必须保留恢复路径。
+- 负载均衡器支持 Upgrade、长连接超时和排空；网络断开不能触发无条件的业务重试。
+
+## 7. 可靠结果订阅
+
+建议独立使用 WSS 入口 `/v1/events/connect` 与子协议 `orbit.events.v1`，区分 Worker 消费权和结果订阅权。具体路径待评审。
+
+事件包含 `event_id`、资源类型、资源 ID、状态版本、事件类型及结果引用，可表达任务与流程事件。平台先持久化事件与交付状态，再发送 `event.deliver`；接收方完成自身的可靠处理后发送 `event.ack`。
+
+未确认事件可重新发送，订阅方按事件 ID 去重；同一资源按状态版本处理迟到信息，不承诺跨资源全局顺序。事件保留到期、订阅失效与补偿查询行为必须公开。
+
+实时控制台展示可使用合并后的进度通知，但业务流程推进不能依赖只有在线时才能收到的消息。
+
+Weave 消费 Pulse 的内部持久化事件，不经此对外订阅入口；其事务与去重要求见 [流程协作](06-workflow-spec.md#5-pulse-与-weave-的事务协作)。
+
+## 8. 版本与协议验证
+
+HTTP `/v1` 与 WS 子协议分别标识兼容边界，业务处理器版本独立。新增可选字段应兼容旧客户端；未知关键消息、状态或枚举不能被当作成功。
+
+协议测试应覆盖断线、重复、迟到、会话切换、局部批量失败与凭据撤销。OpenAPI 与 WS Schema 要进入版本控制和兼容性检查，禁止服务端与 SDK 各自维护不同的状态解释。
--- a/docs/04-reliability-and-data.md
+++ b/docs/04-reliability-and-data.md
@@ -0,0 +1,160 @@
+# Orbit 可靠性与数据模型
+
+> 版本 0.2 · 2026-09-17。本文定义首版设计约束与建议状态机，不是已实现的可靠性保证。
+
+## 1. 权威状态与核心不变量
+
+MySQL 保存任务、执行权、计划进度、流程、步骤、信号、结果与幂等索引的权威状态。内存队列、连接表与时间索引是加速结构，丢失后可以从权威状态重建。
+
+必须维持以下不变量：
+
+1. 确认任务受理前，任务、提交幂等记录及必要事件已经按约定持久化。
+2. 在一个任务当前状态版本中，至多存在一个有效执行授权；跨节点领取使用事务与条件更新协调。
+3. 新操作必须携带当前有效的执行尝试和租约凭据；旧执行不能覆盖新状态。
+4. 任务终态、尝试结果和必要的结果事件在同一个数据库事务中更新。
+5. 调度触发记录、对应任务和计划进度的推进原子提交。
+6. 重复提交、重复派发、重复结果和重复事件交付都有明确去重范围。
+7. 没有证据确定业务副作用时，不将通信失败直接解释为业务失败并无条件重跑。
+8. 人工干预保留历史、原因与身份；不能通过直接修改数据库状态绕过业务确认。
+9. 流程步骤推进与下一步任务创建共享事务；异步接续的内部事件必须持久化并可去重。
+10. 流程绑定的定义版本不被发布操作替换；信号和任务结果只能推进匹配的步骤激活。
+11. 有界查询轮次、对应任务与唤醒关联持久化并去重；重启、暂停继续及执行重试不重置预算。
+12. 按暂停设计，流程控制版本与通用执行门控一致更新；阻止新的授权，同时保留在途结果及可恢复的待续推进记录。
+
+平台允许按策略重复投递或恢复执行，不承诺任意外部业务效果“恰好一次”。业务幂等和资源端执行代次校验仍由接入方落实。
+
+## 2. 建议任务状态机
+
+| 状态 | 含义 |
+| --- | --- |
+| `WAITING` | 等待执行，包含未来执行与退避等待，以 `available_at` 决定最早派发时间 |
+| `LEASED` | 已分配给一个执行尝试，等待开始确认 |
+| `RUNNING` | 已授权处理器开始，租约管理执行权 |
+| `NEEDS_REVIEW` | 结果未知或需要人工/业务核查，不自动重新产生副作用 |
+| `SUCCEEDED` | 已保存处理器约定的成功结果 |
+| `FAILED` | 已知失败、不可重试，或符合结束条件 |
+| `CANCELLED` | 已阻止开始，或 Worker 已报告停止且取消结果可确认 |
+
+```mermaid
+stateDiagram-v2
+    [*] --> WAITING
+    WAITING --> LEASED: 原子取得执行授权
+    LEASED --> RUNNING: 确认开始
+    LEASED --> WAITING: 未授权开始且领取失效
+    LEASED --> FAILED: 未授权开始且时限或策略已耗尽
+    WAITING --> CANCELLED: 取消生效
+    LEASED --> CANCELLED: 开始前取消生效
+    WAITING --> FAILED: 时限或策略不再允许执行
+    RUNNING --> SUCCEEDED: 结果可靠保存
+    RUNNING --> WAITING: 满足安全重试条件
+    RUNNING --> FAILED: 已知失败且结束
+    RUNNING --> NEEDS_REVIEW: 结果未知且不可安全重试
+    RUNNING --> CANCELLED: 停止已确认
+    NEEDS_REVIEW --> SUCCEEDED: 核查确认成功
+    NEEDS_REVIEW --> FAILED: 核查确认失败并结束
+```
+
+`cancel_requested` 是独立的持久化意图，不直接把运行任务变为 `CANCELLED`。取消请求与成功上报竞争时按事务确定的有效转换处理；不能覆盖已经确认的成功结果。
+
+单次超时、总时限和租约过期都要结合当前阶段与任务安全等级判断。运行中无法确认效果的任务应进入核查；不能仅因为超时就声称业务已停止。
+
+核查操作需要证据引用、权限和审计。核查前的迟到结果可以作为证据保存，但无效尝试不能直接改写任务终态。
+
+人工重试的建议是创建关联新任务，旧任务终态不回退；此项参见 [待确认决策](README.md#需要继续确认的事项)。
+
+管理审计随对应状态变更同事务追加，应用日常权限不允许改写历史审计。更正通过新的关联记录表达；归档、导出和到期清理另设权限与审计。数据库管理员级别的防篡改证据及长期留存方案在生产审计要求确定后另行设计，不能将普通日志等同于业务审计证据。
+
+## 3. 执行尝试与租约
+
+一次尝试记录独立 ID、所属任务、授权代次、Worker 实例、当前会话、有效期、批准开始时间、结束时间、错误与结果摘要。终结的尝试不被下一次尝试覆盖。
+
+- 使用数据库时间作为租约判定依据；数据库及运行环境需要时钟监控。
+- 领取、开始、续租、完成、取消与恢复采用明确的条件更新和受影响行数判断。
+- 处理器在数据库事务之外运行。不得持锁等待网络、执行业务逻辑或等待人工。
+- 过期回收必须再次校验租约和状态版本，避免与刚成功的续租或完成操作竞争。
+- 租约过期与重试安全性分别判断；失联不会自动证明旧处理器没有产生副作用。
+- 执行凭据应具备不可猜测性；顺序代次与秘密凭据职责分开，具体表示在协议评审中确定。
+
+同业务键的并发限制只约束平台授予的有效许可。旧进程或已经发出的外部请求无法被数据库锁自动撤回，接入方仍需业务唯一约束、幂等或资源端 fencing。
+
+## 4. 数据分组建议
+
+下表是概念分组。实际 Go 模型、表名和已落实约束见 [数据模型基线](07-data-model.md)，初始 DDL 已建立：
+
+| 数据组 | 建议实体及关键约束 |
+| --- | --- |
+| 接入与资源 | 应用、命名空间、凭据引用、队列、配额；作用域校验覆盖读写 |
+| 任务 | `tasks`；保存当前状态、状态版本、处理器与参数快照、到期时间、当前尝试 |
+| 提交幂等 | `submission_keys`；命名空间与键唯一，保存请求语义摘要及原任务引用 |
+| 执行尝试 | `task_attempts`；尝试 ID 唯一，保留每次授权与结果 |
+| 关键状态事件 | `task_events`；状态转换追加记录，与任务状态版本关联 |
+| Worker 与执行许可 | 会话代次、恢复所需归属、可回收的并发许可；连接对象本身仅在内存 |
+| 通用执行门控 | Pulse 管理的门控标识、允许/暂停标记和控制版本；流程任务关联门控，领取/开始与控制更新按统一锁定或版本协议串行化 |
+| 计划 | `schedules`；定义版本、时区、生效边界、下一触发点与策略 |
+| 触发 | `schedule_occurrences`；建议同计划同一 UTC 计划触发时间唯一 |
+| 结果交付 | `result_events`、`event_deliveries`；事件与订阅交付唯一，确认和补投状态持久化 |
+| 流程定义 | `workflow_definitions`、`workflow_definition_versions`；发布版本不可变，记录定义摘要及发布审计 |
+| 流程实例 | `workflow_instances`；实例、启动幂等身份、定义版本、状态版本、暂停标记、控制版本、门控关联与策略快照 |
+| 步骤与激活 | `workflow_steps`、`workflow_activations`；实例内步骤/激活唯一，绑定当前 Pulse 任务 |
+| 信号与等待 | `workflow_signals`、`workflow_waits`；实例内信号身份唯一，保存目标关联、截止时间与消费状态 |
+| 有界查询 | 查询节点检查点与 `workflow_poll_rounds`；命名空间/实例/步骤激活/轮次唯一，保存任务关联、已用轮次、截止时间、下次查询时间及结果 |
+| 流程接续 | `workflow_inbox`、待续推进记录；源事件/消费者唯一，推进与消费确认同事务 |
+| 管理审计 | 操作主体、原因、资源版本、前后摘要和证据引用 |
+
+活跃任务访问路径与历史归档分离。索引围绕命名空间、队列/逻辑分区、状态、到期时间和租约到期时间设计，并以真实执行计划验证。
+
+同一任务、流程及步骤任务需要原子更新的数据必须处于同一事务可覆盖的数据库中。未来物理分片时先明确路由单元及全局配额边界，不能让跨库更新沿用单库原子性假设。流程状态模型以 [Weave 设计](06-workflow-spec.md) 为准，不能混用任务与流程状态。
+
+## 5. 关键事务
+
+| 事务 | 必须一起提交的内容 |
+| --- | --- |
+| 受理 | 提交幂等记录、任务、受理事件 |
+| 领取 | 校验可执行条件与有效门控、取得额度、创建尝试、更新当前执行归属 |
+| 开始 | 校验当前授权、门控与取消意图、记录批准开始状态 |
+| 续租 | 校验当前尝试/会话/版本、更新有效期；批量操作逐项给出结果 |
+| 完成 / 失败 / 转核查 | 尝试结果、任务状态、额度释放、关键事件、必要结果通知与内部流程交付记录 |
+| 取消 | 取消意图或开始前取消终态、管理审计、必要通知 |
+| 调度触发 | 触发去重记录、任务创建、计划进度推进 |
+| 流程启动 / 推进 | 实例与步骤变化、待续推进检查点、下一步任务或等待建立、流程事件 |
+| 内部事件消费 | 去重校验、步骤与流程推进、后续任务创建、消费确认 |
+| 信号受理 / 消费 | 受理时保存幂等与待处理记录；消费时原子校验等待、推进并确认消费 |
+| 流程暂停 / 继续 | 实例控制版本、暂停标记、Pulse 通用执行门控、管理审计与必要待续推进记录 |
+| 查询下一轮 | 校验门控与预算、写入唯一轮次、计数、创建对应任务、确认内部唤醒消费 |
+
+任务领取可评估短事务配合 `SELECT ... FOR UPDATE SKIP LOCKED`；其适用场景是队列类访问，不应被用于跳过业务一致性校验。[MySQL 锁定读取说明](https://dev.mysql.com/doc/refman/8.4/en/innodb-locking-reads.html)
+
+所有事务明确锁定顺序，处理死锁和提交结果不明。提交结果不明时先通过稳定操作身份核对，不能换身份重试造成额外任务。
+
+## 6. 可靠衔接
+
+### 6.1 业务系统到平台
+
+接入方保存业务数据与向 Orbit 提交任务、启动流程或发送信号之间跨越两个数据库边界。业务侧可在本地事务内写入业务变更和 Outbox，再以稳定幂等键提交对应接口，受理后标记已送达。
+
+Orbit 数据库事务不能自动包含 接入方的业务事务。SDK 的事务接入组件只辅助接入方在自己的数据库写入待发请求，核心 HTTP / WS 客户端不绑定业务 ORM。[事务 Outbox 参考](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html)
+
+### 6.2 平台到结果接收方
+
+结果事件与终态同事务保存，投递状态独立跟踪。接收方可靠处理后确认；确认丢失则重复交付，由接收方去重。
+
+事件投递不能仅依赖内存通知，也不能未经处理提交次序问题就用自增 ID 的最大值作为“此前全部已处理”的游标。首版建议使用明确的订阅交付记录。
+
+### 6.3 Pulse 到 Weave
+
+任务结果和待核查等关键状态变化，原子产生持久化内部事件与交付记录。Weave 使用事件身份、任务状态版本、当前步骤激活去重，在推进事务中确认消费。事件处理失败可再次消费；重复消费不得创建第二份后续任务。
+
+内部事件暂时未消费时，流程详情应能区分“任务已有结果”和“编排尚未推进”，积压需要监控及恢复扫描。具体事务边界见 [流程协作](06-workflow-spec.md#5-pulse-与-weave-的事务协作)。
+
+暂停不停止内部结果的可靠记录。若消费事件时暂不允许新步骤推进，应同时保存待续推进检查点；只标记事件已消费却没有后续恢复记录，会导致流程在继续后停滞。有界查询同样不能仅在内存增加轮次、设置定时器或保存未完成的下一轮计划。
+
+## 7. 保留、归档与恢复
+
+- 任务与流程历史、幂等键、信号、内外部事件、管理审计分别制定保留策略。
+- 清理任务主体不自动清理幂等索引。去重窗口须覆盖约定的补发与恢复窗口，长期业务幂等由业务系统维护。
+- 有未确认交付的事件不能被普通归档清理无声删除；保留到期应告警并执行已定义的补偿流程。
+- 备份需覆盖任务、计划、幂等、执行门控、流程定义、实例、查询轮次与预算、信号、事件及配置的一致恢复范围，包含必要的日志与密钥管理安排。
+- 恢复旧备份后，可能已有外部业务效果而平台记录回退。必须停止派发、使恢复前的会话与租约失效，并完成必要对账后再开放执行。
+- 数据库故障切换与备份恢复是不同故障模型，分别定义验证和可接受损失范围。
+
+MySQL 持久化建议基线为 `innodb_flush_log_at_trx_commit=1`，启用 binlog 时采用 `sync_binlog=1`。副本故障切换的确认语义、RPO / RTO 仍要由具体高可用方案决定。[MySQL 持久化配置](https://dev.mysql.com/doc/refman/8.4/en/innodb-parameters.html#sysvar_innodb_flush_log_at_trx_commit)
--- a/docs/05-production-acceptance.md
+++ b/docs/05-production-acceptance.md
@@ -0,0 +1,110 @@
+# Orbit 生产验收与发布门槛
+
+> 版本 0.2 · 2026-09-17。本文是验收计划，所有项目当前均为待实现、待验证。没有已通过的测试或容量结论。
+
+## 1. 验收对象与证据
+
+统一验证平台中的 Pulse 任务模块、Weave 流程模块、MySQL、HTTP / WS 协议和业务 SDK。包含模拟业务处理器及模拟外部渠道，以验证副作用与结果确认边界。
+
+每份验收报告记录：版本、数据库配置、拓扑、硬件、网络条件、参数、数据量、复现步骤、预期与实际结果、关键指标、异常记录和遗留问题。
+
+稳定性目标必须表述为在指定故障模型与负载下满足约定，不使用脱离环境的“绝不丢失”或“支持无限租户”作为测试结论。
+
+## 2. 必须覆盖的正确性与故障场景
+
+| 编号 | 场景 | 期望结果 |
+| --- | --- | --- |
+| A01 | 相同幂等键重复提交、并发提交 | 返回同一任务，不创建第二份工作；参数冲突明确拒绝 |
+| A02 | 受理已提交，HTTP 响应丢失 | 使用原键可查到任务，重试不重复创建 |
+| A03 | 多节点同时领取同一任务 | 仅一个有效授权，配额与尝试记录一致 |
+| A04 | 派发落库后节点宕机，消息未送达 | 未开始尝试可回收，任务仍可追踪并恢复 |
+| A05 | 开始确认或完成确认丢失 | SDK 按操作身份核对/重报，不能错误地再执行一次已确认操作 |
+| A06 | 业务写入成功，Worker 在上报前崩溃 | 平台允许恢复；业务幂等返回原结果，副作用未知时转核查 |
+| A07 | 旧 Worker 暂停后恢复，租约已被替代 | 旧结果不覆盖新状态，资源端防护按接入契约生效 |
+| A08 | 续租与过期回收、完成操作竞争 | 事务条件决定唯一合法转换，额度不重复释放 |
+| A09 | WS 断线后重连不同节点 | 重新鉴权与恢复核对，旧会话不能继续控制新会话归属 |
+| A10 | Worker 容量消息重复、发送缓冲满 | 不重复发放额度，不无限积压内存，不丢弃关键结果恢复信息 |
+| A11 | 取消与开始/完成竞争 | 终态与已知结果一致，取消意图不伪装成业务回滚 |
+| A12 | 外部平台已受理但响应超时 | 按处理器安全策略核查，不能盲目重复提交 |
+| A13 | 多调度节点处理同一触发点 | 仅一个有效触发实例，任务与计划进度原子更新 |
+| A14 | 停机、时区变化、计划修改与恢复 | 补跑/跳过/合并遵守已定义版本边界，全部可追溯 |
+| A15 | 结果接收方停机或确认丢失 | 事件保留并可重投，接收方去重，积压可观测 |
+| A16 | 同业务键并发与跨节点配额竞争 | 有效许可满足约束，过期执行副作用按业务防护处理 |
+| A17 | 使用另一应用/队列身份读写或恢复任务 | 被拒绝，敏感参数与凭据不泄露 |
+| A18 | MySQL 短暂不可用或主节点切换 | 不发出无依据的成功确认；恢复后任务可核对 |
+| A19 | 平台与 Worker 滚动升级 | 兼容版本继续服务，旧任务找到兼容处理器或明确等待 |
+| A20 | 清理与归档同时发生重复补交/事件补投 | 幂等与未确认事件不被无声破坏 |
+| W01 | 创建流程下一步任务时中断事务 | 流程状态与任务创建同时提交或回滚 |
+| W02 | 任务完成后流程处理节点宕机 | 内部结果事件可恢复消费，步骤不重复推进 |
+| W03 | 信号提前、重复或迟到 | 已存在实例可保存早到信号，消费去重且匹配正确步骤 |
+| W04 | 人工等待或定时等待期间重启 | 等待状态恢复，不长期占用业务 Worker |
+| W05 | 并行步骤部分成功、部分失败 | 汇合规则明确，成功副作用保留，重试不越过业务安全规则 |
+| W06 | 新流程版本发布 | 已运行实例继续使用冻结版本，不悄悄改变历史步骤 |
+| W07 | 取消流程时仍有任务执行 | 流程如实反映取消推进与待核查状态，不宣称已撤销副作用 |
+| W08 | 同一汇合点的多个结果并发到达 | 按汇合规则只推进一次、只创建一份后继任务 |
+| W09 | 信号受理、定时唤醒与取消竞争 | 原子决定唯一有效推进；已按时受理信号不因消费积压被误判超时 |
+| W10 | 人工恢复后收到旧激活结果或重复恢复请求 | 旧结果不推进新激活，恢复去重，保留审计与业务幂等 |
+| W11 | 查询正常返回处理中，期间部分请求失败 | 查询轮次与 Pulse 尝试独立计数；处理中按间隔进入下一轮，请求重试不新增轮次 |
+| W12 | 轮次用完、总时限到达或单轮重试耗尽 | 按规则转核查；不换任务或轮次绕过上限，不再次调用业务提交接口 |
+| W13 | 保存查询结果、建立等待或创建下一轮时宕机 | 从持久化轮次与检查点恢复，同一轮只创建一项任务，预算不丢失或重复扣减 |
+| W14 | 暂停与创建步骤、任务领取、开始及重试竞争 | 按控制版本及门控决定唯一有效顺序，暂停后不新增授权；已授权工作继续收集结果 |
+| W15 | 暂停期间收到结果/信号、到期或重启，然后继续 | 结果和待续推进记录可恢复，原版本与预算保留；按冻结计时规则处理到期，不集中补查 |
+| W16 | 最终回执、查询结果与下一轮唤醒并发或迟到 | 只完成一次等待并创建一份后继工作，停止后续轮次，冲突或旧结果不能覆盖结论 |
+| W17 | SDK 重复发布、同版本内容冲突或发布非法定义 | 同内容幂等，不同内容拒绝；非法表达式、引用及无界预算被拒绝，运行实例版本不变 |
+
+W11–W17 中的字段与暂停/计时算法按技术评审后的规范执行；这些验收项不表示当前建议已经实现或测试通过。
+
+验收还需覆盖日志脱敏、权限撤销、消息超限、死锁、连接重连风暴、磁盘容量告警及进程强制终止。
+
+## 3. 性能负载模型
+
+租户数量用于推导业务量，不能直接等同于连接数、队列数或每秒任务数。至少建立以下维度：
+
+- 平均与峰值提交任务数、批量大小、瞬时集中触发规模。
+- 同时运行任务数、任务耗时分布、续租频率与重试比例。
+- Worker 连接数、每连接并发、空闲连接比例、重连频率。
+- 参数/结果大小、事件数量、保存周期、历史查询并发。
+- 定时计划数、到期分布、漏跑补偿规模与允许的恢复窗口。
+- 流程实例数、每实例步骤数、并行度、等待实例数与信号速率。
+- 查询轮次与单轮尝试分布、渠道请求峰值，以及大量暂停实例继续时的待续推进规模。
+
+采用短任务、中长任务、混合负载、集中触发、长期积压和故障恢复六类场景。既测空处理器的框架开销，也测可控延迟的模拟外部调用。
+
+## 4. 必须度量的指标
+
+| 指标 | 定义 |
+| --- | --- |
+| 受理延迟 | 发起请求至可靠受理响应，统计 p50 / p95 / p99 |
+| 调度延迟 | 原计划到期时间至变为可派发状态，单独统计漏跑补偿 |
+| 排队与派发延迟 | 可执行时间至授予执行权，以及授予至 Worker 收到/开始 |
+| 吞吐 | 可靠受理、开始、完成、事件交付分别统计 |
+| 数据库负载 | 查询/写入、锁等待、死锁、连接池、日志与磁盘 I/O、复制滞后 |
+| 连接与内存 | 连接数、重连、发送队列、内存、GC、CPU 与网络 |
+| 恢复效果 | 故障发现、重新授权、流程恢复、积压清空的时间与错误数量 |
+| 公平性 | 单个应用突发时其他应用的延迟与额度兑现情况 |
+| 流程推进 | 内部事件至步骤完成/后续任务创建的延迟与积压 |
+| 有界查询与暂停 | 活跃查询节点、轮次/尝试消耗、到期转核查量、暂停实例数、继续后的推进延迟及渠道请求速率 |
+
+开启生产所需持久化、复制、鉴权和审计后再测，报告任何性能优化对可靠性或恢复窗口的影响。
+
+## 5. 发布前必须确定的参数
+
+以下数值当前均为待定：容量目标、延迟目标、可用性目标、RPO / RTO、消息和批量上限、租约/续租/心跳/重连参数、扫描与补跑预算、查询轮次/间隔/总时限与单轮重试预算、暂停继续的推进预算、保留周期、兼容版本范围。
+
+配置之间需要校验，例如续租间隔与安全余量必须允许在租约到期前发现失败；代理空闲超时需与 WS 活性策略协调；最长恢复补发窗口应与幂等和事件保留周期匹配。
+
+## 6. 备份恢复与上线门槛
+
+恢复演练必须实际恢复到隔离环境，核对任务、尝试、计划、幂等、结果事件、流程、暂停控制与执行门控、查询轮次及预算、信号和权限配置。恢复旧数据后需要隔离旧连接与执行凭据，并核查可能已发生的外部效果。
+
+上线前至少具备：
+
+- 已评审的功能、状态机、协议与兼容矩阵。
+- 实际 MySQL 的持久化、复制确认、故障切换及恢复说明。
+- 上述关键故障场景的复现证据与结果核对。
+- 满足约定峰值且保留容量余量的压力测试记录。
+- 监控告警、值守与恢复操作说明，必要的管理权限和审计。
+- 业务接入方的幂等及结果核查验收；真实业务副作用前先完成隔离环境演练。
+- 发布、迁移、回滚/前向修复策略，以及明确的停止扩量条件。
+
+仅有单机演示、正常路径测试或一次吞吐测试，不构成本项目的生产验收通过。
--- a/docs/06-workflow-spec.md
+++ b/docs/06-workflow-spec.md
@@ -0,0 +1,210 @@
+# Weave 流程编排功能与设计
+
+> 版本 0.2 · 2026-09-17。首版功能范围及研发定义发布方式已确认，包含有界重复查询和生产管理能力。具体字段、状态表示、算法及参数仍待技术评审；未实现、未验收。
+
+## 1. 职责与边界
+
+Weave 保存“流程到了哪一步、下一步何时可以开始、正在等待什么”。Pulse 保存“任务交给谁执行、执行权是否有效、能否安全重试、结果是什么”。公共身份、权限、协议、审计和存储由 Orbit 统一提供。
+
+Weave 不执行特定业务逻辑，也不把整段业务代码放入平台进程。实际工作通过 Pulse 派给业务 Worker，业务系统负责业务正确性、幂等、外部结果核查与授权。
+
+首版由研发通过 Go SDK 描述、发布流程，业务处理器仍在业务 Worker 中执行。技术上建议采用显式流程定义与持久化状态机，根据已保存的定义、步骤结果和信号计算推进，不实现任意 Go 业务函数的执行历史重放。
+
+## 2. 已确认的首版能力
+
+| 能力 | 行为与边界 |
+| --- | --- |
+| 顺序步骤 | 前一步达到定义的完成条件后，创建下一步任务 |
+| 条件分支 | 基于已保存、经过类型校验的结果或信号选择路径；不执行任意脚本 |
+| 有限并行与汇合 | 建议先支持结构化并行分支、全部成功后汇合；限制分支数，不默认支持任意交叉汇合 |
+| 等待业务信号 | 持久化等待回执、审核结果等外部输入，不长期占用 Worker |
+| 定时等待 | 持久化截止时间，通过 Pulse 的内部定时任务唤醒 |
+| 有界重复查询 | 外部业务尚在处理中时按间隔查询，达到次数或总时限后转人工核查；不与 Pulse 执行重试混用 |
+| 暂停与继续 | 暂停后停止推进新步骤，继续接收在途结果；恢复后从已保存进度继续 |
+| 异常与人工恢复 | 保存失败或未知结果，按定义暂停相关推进并核查；干预必须有权限、原因与证据 |
+| 取消 | 阻止新步骤，持久化下游取消意图，等待已开始工作的可确认结果 |
+| 查询与审计 | 查询流程版本、每步输入/结果引用、关联任务、执行次数、查询轮次、等待原因、信号、人工操作与状态转换 |
+| 版本固定 | 实例绑定不可变定义版本及实际生效配置，发布新版本不改变运行实例 |
+
+完整审批产品、可视化编辑器、任意循环、动态无限展开、子流程、跨库流程迁移及运行中替换定义不默认进入首版。有界重复查询作为明确受限的节点能力纳入首版，不开放任意回边或无限循环。是否需要补偿步骤及其首版范围另行讨论。
+
+首版通过 SDK / 管理 API 提供运行查看与管理能力；后台操作界面可以调用这些 API，完整图形化控制台的交付范围另定。业务人员自由拖拽编排不纳入本次确认范围。
+
+人工审核可以由业务系统完成，再提交经过授权的信号。Weave 记录提交者和证据，不代替业务系统判断“谁有权批准这笔账”。
+
+## 3. 定义与实例身份
+
+研发在代码中通过 Go SDK 描述步骤与规则，定义源码跟随业务项目进行版本管理和评审，再显式发布到 Orbit。业务服务每次启动不应自动覆盖已发布定义。
+
+建议 SDK 将流程描述生成为可校验的 JSON 定义，表达步骤、输入映射、结果结构、条件、等待、时限和失败策略。Orbit 不执行上传的任意 Go 函数；业务计算和外部请求通过命名、版本化处理器完成。SDK 的构建 API、定义 Schema 及发布命令形式待协议评审。
+
+发布前至少验证引用、可达性、顶层无环、分支穷尽性、结构化汇合、类型匹配与资源上限。有界重复查询封装为一个节点，在节点内部保存轮次和截止时间，不将次数上限展开成大量静态节点。定义发布需要独立权限和审计，版本内容不可变；重复发布同版本同内容可幂等确认，不同内容明确冲突。
+
+| 身份 | 用途 |
+| --- | --- |
+| `definition_id` / `definition_version` | 稳定定义与不可变版本 |
+| `workflow_id` | 一次流程实例；启动请求重试返回原实例 |
+| `step_id` / `activation_id` | 定义中的步骤与该步骤一次具体激活，区分后续人工恢复 |
+| `task_id` / `attempt_id` | Pulse 的一次任务与执行尝试，不能与流程或步骤身份混用 |
+| `poll_round` | 同一次查询节点激活内的查询轮次；一轮关联一个 Pulse 任务，可包含多次执行尝试 |
+| `signal_id` / 关联键 | 信号去重及匹配指定实例、步骤激活或业务操作 |
+
+启动时绑定明确的定义版本、参数版本、处理器兼容要求和策略快照。若允许以“当前版本”启动，首次受理时解析并固定；相同幂等键重报仍返回首次绑定的实例。
+
+初次启动的幂等键至少在命名空间和操作类型内唯一。同键不同语义输入必须冲突；不因新定义发布就生成另一份流程。
+
+## 4. 建议状态模型
+
+流程状态与任务状态分别管理，不能用“最后一个任务成功”替代整个流程的成功条件。
+
+| 流程状态 | 含义 |
+| --- | --- |
+| `RUNNING` | 存在可推进步骤或仍在执行/排队/退避的任务 |
+| `WAITING` | 没有可立即推进的步骤，剩余路径等待信号或时间 |
+| `CANCELLING` | 已接受取消意图，正在确认关联工作的停止或结果 |
+| `NEEDS_REVIEW` | 存在阻塞推进的失败、未知效果或需人工处理事项 |
+| `SUCCEEDED` | 所有要求完成的路径和汇合条件已经满足 |
+| `FAILED` | 已确定无法完成，且所有已激活工作均已结清或确认停止 |
+| `CANCELLED` | 取消已完成；不表示历史上已成功的业务效果被撤销 |
+
+存在未知副作用时不能进入一个暗示“全部已结清”的终态。建议异常核查优先显示为 `NEEDS_REVIEW`，同时保留取消意图及每个分支的真实状态；状态汇总优先级在协议评审中固定。
+
+暂停建议用独立持久化标记 `paused` 与控制版本表达，不覆盖上述执行状态：实例可以同时显示“已暂停”和“有任务执行中”或“待核查”。恢复仅解除暂停，不自动解除核查或撤销取消。具体字段与汇总展示规则仍待协议评审。
+
+步骤单独保存等待前置条件、等待任务、等待信号/时间、完成、失败、跳过或待核查等阶段及状态版本。步骤任务排队不代表业务已经运行；详情应展示 Pulse 的实际执行阶段。
+
+实例终态不静默回退。对已结束流程重新执行，建议创建带来源关联的新实例，重新校验业务幂等；首版是否支持从已完成步骤继续、以及需要哪些业务证据，另行评审。
+
+## 5. Pulse 与 Weave 的事务协作
+
+首版两个模块处于同一 MySQL 事务范围，通过应用层接口明确传递事务上下文，不互相任意写表。
+
+| 操作 | 原子提交内容 |
+| --- | --- |
+| 启动流程 | 启动幂等记录、实例与首批激活步骤、对应 Pulse 任务、状态事件 |
+| 保存任务结果 | Pulse 任务/尝试结果、额度释放、结果事件及内部交付记录 |
+| 接续任务结果 | 核对实例与步骤激活、消费去重、步骤变化、流程推进、后续任务或等待记录、内部事件处理确认 |
+| 建立定时等待 | 步骤等待条件、截止时间、对应的 Pulse 内部定时任务 |
+| 接收信号 | 幂等记录、信号内容与身份、持久化待处理记录 |
+| 消费信号 / 定时唤醒 | 校验等待条件与状态版本、消费标记、流程推进、后续任务创建 |
+| 查询轮次推进 | 校验暂停/取消、轮次/时间预算，创建唯一轮次记录与对应任务，或保存下一次唤醒 |
+| 暂停 / 继续 | 控制标记与版本、通用执行门控、管理审计、必要的持久化待续推进记录 |
+
+内部结果交付可使用公共持久化事件表加 `workflow_inbox` 记录。事件生成与交付记录必须跟随 Pulse 的状态变化一起提交，不能先提交任务再仅通过内存调用 Weave。
+
+任务自动重试期间步骤仍关联原任务；任务进入 `NEEDS_REVIEW` 时发送内部状态事件，让流程可见地进入核查。任务后来被核查确认为终态时，再由新的状态版本事件推进。
+
+处理事件时校验命名空间、流程、步骤激活、查询轮次、当前任务 ID 与源状态版本。重复事件只能产生一次推进；旧激活或旧轮次的迟到事件保留记录，不启动当前激活的后续步骤。并行汇合在短事务内协调同一实例/汇合点状态，确保后继任务只生成一次。
+
+同一实例的一次推进有步骤数和耗时预算。超过预算时原子保存检查点和待续推进记录，再由有界扫描继续；不能提交部分展开状态后只依赖内存继续循环。
+
+这套内部交付不经过对外 WS 订阅。WS 用于业务 Worker 通信或业务结果通知，不承担两个模块之间唯一的可靠通道。
+
+## 6. 信号与持久化等待
+
+### 6.1 信号与时间唤醒
+
+信号携带稳定幂等身份、目标实例、信号类型、目标步骤/业务操作关联、参数版本及证据引用。认证身份与提交范围由服务端核验，不能仅凭流程 ID 注入信号。
+
+- 实例已经存在但尚未进入等待时，允许将匹配该定义的早到信号持久化；达到匹配条件后再消费。
+- 实例不存在时明确返回未找到，不创建无归属信号。业务侧先完成幂等启动，再通过 Outbox 补交信号。
+- 相同信号 ID、相同语义内容返回原受理结果；不同内容明确冲突。
+- 一次等待默认消费一次匹配信号；广播、多次聚合和跨实例信号不隐式支持。
+- 信号关联必须能区分具体业务操作，不能只按“审核通过”等类型匹配，避免旧业务批次、旧步骤或旧恢复轮次的信号误用。
+- 信号受理成功只表示已可靠保存，消费与步骤推进状态可另外查询。
+
+定时等待使用已保存的截止时间和内部定时任务。定时唤醒由平台执行角色处理，不需要业务 Worker 长期占用连接槽位。任务结果与后续等待消费仍遵守幂等和事务规则。
+
+信号、超时与取消竞争时，按等待记录的状态版本原子决定结果。采用信号持久化受理时间与等待截止时间判断是否按时到达，不能因消费积压把已经按时受理的信号误判为超时；截止点的包含规则待协议冻结。取消另一条唤醒路径后，迟到事件只留痕，不再次推进。
+
+未匹配信号数量、参数大小、保留时间与等待时限必须有上限。到期清理需要可观测且有明确规则，不能悄悄丢掉仍有效的等待依据。
+
+### 6.2 有界重复查询
+
+**功能已确认**：查询成功但外部业务仍在处理中，由 Weave 等待后发起下一轮；查询请求失败，由 Pulse 在当前轮次内按安全策略重试。达到轮次或总时限上限后转人工核查，不直接认定外部业务失败。
+
+以下为实现建议，具体字段与边界待技术评审：
+
+| 内容 | 建议约束 |
+| --- | --- |
+| 查询目标 | 固定查询处理器、版本和外部业务操作标识；恢复查询不能重新调用提交接口 |
+| 轮次上限 | `max_rounds` 为有限正整数；创建轮次记录与查询任务时原子计数，不因重复事件或重启重复增加 |
+| 总时限 | 从节点激活时固定 `deadline_at`；建议同时设置轮次与时间上限，先到者阻止新一轮 |
+| 查询间隔 | 建议从上一轮完成且结果仍为处理中时计算下一次时间，可设有上限的退避与抖动；不按错过的间隔集中补跑 |
+| 单轮执行重试 | Pulse 使用独立且有限的尝试预算，自动重试保持该轮任务 ID；受节点剩余时限约束 |
+| 结果映射 | 明确区分处理中、业务确认成功、业务确认失败和需要核查；未知值不能默认为成功或继续循环 |
+
+查询任务自身成功表示取得了一份有效结果。其中“处理中”使 Weave 保存等待与下一次唤醒；最终业务结果则结束查询节点，按定义推进或进入失败处理。单轮请求重试耗尽应转核查，不能通过新建一轮绕过已耗尽的重试预算。
+
+每轮只创建一个查询任务，以命名空间、实例、步骤激活和轮次形成稳定去重身份。轮次之间释放业务 Worker 槽位，等待依赖数据库记录与 Pulse 内部定时唤醒；SDK 不在处理器中长期 sleep 或维护内存轮询循环。
+
+发布和受理时校验轮次、单轮尝试、超时和总时限的组合上限，避免两层次数相乘后超过外部渠道或平台预算。未完成上一轮前不得并发启动下一轮。最后一轮仍为处理中、等待到期或当前轮次重试耗尽时，保存核查原因及已知结果。
+
+截止时间到达后不再授权新查询或其执行重试；已经授权的请求仍需收集结果。迟到结果可保存为证据，不自动清除到期后的核查状态。建议以结果持久化受理时间而非内部事件消费时间判断是否按时到达，避免消费积压造成误判。
+
+若查询期间也允许接收业务最终回执，回执与查询结果竞争同一等待/激活版本，只能完成一次。最终回执胜出后停止后续轮次；在途只读查询仍收集结果并审计，迟到或冲突结果不得再次推进或覆盖已确认结果。
+
+## 7. 重试、失败与人工干预
+
+### 7.1 暂停与继续
+
+**功能已确认**：暂停阻止新步骤推进，保留已完成进度，继续接收在途结果与外部回执；继续操作从持久化进度恢复。暂停不表示已经停止外部业务操作。
+
+以下细则为设计建议：
+
+- 暂停与继续带预期控制版本、稳定操作身份、操作人及原因；状态与审计一起提交。新步骤创建必须原子检查控制版本。
+- 建议暂停还阻止关联任务的新领取、开始授权和执行重试，包含已经创建但尚未开始的任务。由 Pulse 的通用执行门控与 Weave 控制状态同事务更新，领取/开始时读取权威门控，避免仅暂停流程循环却继续派发旧队列任务。
+- 暂停前已获得开始授权的尝试仍可运行、续租和上报，保留时限与安全约束。暂停与开始竞争按事务顺序决定；“暂停成功”只表示门控已持久化，不表示所有在途请求已停止。
+- 在暂停期间可靠保存任务结果、信号和到期事实，必要时进入核查或结清已有工作；不创建新的业务步骤或查询轮次。即使内部事件已确认消费，也要保存待续推进状态，避免恢复后无事件可推进。
+- 建议暂停不延长原业务截止时间，查询节点、任务时限与信号有效期继续计时。恢复时先核对已受理结果、信号和原截止时间，不能把过期查询重新激活；时间策略在协议冻结前确认。
+- 恢复按配额和推进预算处理积压，不重置已用查询轮次和执行尝试，不补发每一个错过的查询时间点。恢复不改变原流程版本，不清除取消或待核查条件。
+
+### 7.2 执行失败与人工恢复
+
+一个业务步骤的自动执行重试归 Pulse 管理。Weave 不对 Pulse 的每次暂时失败再创建新任务，也不叠加另一层指数重试。
+
+建议步骤最终失败后，按固定策略进入流程核查或结束处理。并行分支部分失败时，不创建依赖该汇合点的后续步骤；按定义停止新派发、请求取消其余活动分支并收集结果。只有所有活动工作均已结清且没有未知效果，才可按策略进入失败终态。
+
+对仍处于核查中的流程进行人工重试时，必须通过 Weave 的恢复入口：
+
+1. 校验权限、当前状态版本、步骤归属、失败类别与副作用证据。
+2. 确认符合安全重试条件；“未收到响应”本身不构成条件。
+3. 在一个事务内记录管理操作，创建新的步骤激活及关联 Pulse 任务，并固定关联关系。
+4. 保留旧激活与旧任务结果，沿用恰当的业务幂等身份。
+
+这是人工恢复的建议模型，具体 API 在评审后冻结。普通任务人工重试入口应拒绝绕过流程管理的关联任务请求。已经确认成功的步骤不能通过“重试流程”随意再执行一次。
+
+取消和补偿是不同业务操作。若未来增加补偿，补偿本身也必须是有权限、可审计、可重试或可核查的业务步骤；不能宣称撤销流程就能撤回已经生效的外部业务操作。
+
+## 8. 通用接入示例
+
+以下只展示模块协作，不替代接入方的业务规则与审核：
+
+```text
+业务系统提交外部作业处理流程
+  → Pulse 执行输入校验任务
+  → Weave 按结果进入业务审核信号等待
+  → Pulse 执行数据准备任务（业务侧保证同一操作幂等）
+  → Pulse 执行外部作业提交任务
+  → Weave 等待回执信号，或通过有界重复查询节点获取最终结果
+  → 根据业务确认的最终结果完成 / 进入核查
+```
+
+“外部作业提交任务成功”可能仅代表渠道受理，不能直接等同于外部作业最终成功。首版有界重复查询节点负责受限轮询，业务方也可以在平台外负责回执采集，再以信号推进流程。查询和核查围绕原外部操作身份进行，不能因没有最终结果就重复提交外部作业。
+
+## 9. 容量、版本与验收
+
+租户数不等于流程并行分支数。禁止将大规模跨租户批处理塞入一个无界流程；按业务单元创建受限实例，批量启动也要配额、背压和逐项幂等。
+
+限制实例步骤数、并行度、查询轮次、单轮重试、每次推进量、输入/输出大小、信号积压与历史保留量。长时间等待只保留持久化状态；扫描依赖到期索引和待处理记录，不能全表遍历所有等待实例。
+
+旧定义、参数解释与处理器版本在仍有运行实例时必须保持可用，或明确进入可观测的版本不兼容等待；升级不能悄悄把旧实例转到新逻辑。
+
+功能范围已确认。实施前仍需评审：SDK 构建 API、定义 Schema、分支表达式、并行失败策略、暂停门控及计时规则、轮询预算与截止边界、人工恢复身份模型、协议字段、资源上限与保留周期。验收覆盖 [生产验收](05-production-acceptance.md) 的流程场景，尤其是暂停竞争、轮次恢复、查询与回执竞争及版本发布。
+
+## 10. 决策记录
+
+- 0.1：提出流程功能草案，Weave 首版范围待讨论。
+- 0.2：确认研发通过 Go SDK 定义发布，确认顺序、分支、并行汇合、信号和定时等待，将有界重复查询纳入首版；确认暂停/继续、取消、人工核查恢复、版本固定与全程追踪。具体技术细则保留为建议，尚未通过实现验证。
+
+公共数据约束见 [可靠性与数据模型](04-reliability-and-data.md)，对外接口草案见 [HTTP 与 WS 协议](03-http-websocket-protocol.md)。
--- a/docs/07-data-model.md
+++ b/docs/07-data-model.md
@@ -0,0 +1,105 @@
+# 数据模型与实现基线
+
+更新：2026-09-17。当前为基础实现阶段，完整调度与编排引擎仍在开发计划中。
+
+## 1. 模块与依赖
+
+- `model/`：ID、摘要、JSON、命名空间记录等公共原语。
+- `platform/model/`：应用、命名空间、凭据、幂等、事件、订阅交付及审计。
+- `pulse/model/`：队列、执行门控、会话、任务、尝试、回执、并发许可和调度计划。
+- `weave/model/`：定义及不可变版本、实例、步骤激活、等待、信号、查询轮次与恢复记录。
+- `internal/storage/mysql/`：连接、事务与显式迁移，不向 SDK 暴露。
+- `sdk/go/`：独立 Go module；对外 DTO 与服务端模型分别维护。
+
+模型使用普通 Go struct 与 `db` 标签，模型与持久化字段提供中文注释，SQL 表和字段同步维护中文 COMMENT。SQL 是可审查的版本化迁移。目前未引入 ORM，也没有自动同步表结构。
+
+## 2. 存储约定
+
+| 项目 | 当前实现 |
+| --- | --- |
+| 数据库基线 | MySQL 8.4+，本轮在 8.4.10 验证 |
+| Go 工具链 | Go 1.27.1；服务端和 SDK 分别编译测试 |
+| 标识 | 128 位加密随机 ID；数据库 `BINARY(16)`，对外 32 位小写十六进制字符串 |
+| 摘要 | SHA-256，数据库 `BINARY(32)`；执行令牌及凭据原文不进入模型 |
+| 租户隔离 | 运行实体以 `(namespace_id, id)` 为主键，具体资源关联使用包含命名空间的复合外键 |
+| 时间 | `DATETIME(6)`，数据库会话与驱动统一 UTC；运行授权依赖数据库时间 |
+| 状态 | Go 类型常量 + SQL `CHECK`；状态版本独立于时间戳 |
+| CAS | `revision` 从 1 开始；服务层必须带期望版本条件更新并检查受影响行数 |
+| 暂停 | 实例执行状态与 `paused` 分开，控制版本与通用门控同事务协调 |
+| 参数 | 版本化 JSON 文档或业务侧引用；平台不内置行业字段 |
+| 删除 | 关联数据默认 `RESTRICT`，没有级联删除执行历史 |
+| 不可变历史 | 流程版本、计划版本、状态事件、审计事件的 `UPDATE` 被数据库触发器拒绝 |
+
+随机 ID 的索引成本需要后续容量测试，不将该选择描述为已经验证的大规模吞吐保证。运行账户应最小授权，迁移与保留清理使用不同身份；触发器不是对数据库管理员的防篡改保证。
+
+## 3. 实体清单
+
+下表与初始迁移中的 30 个实体一致；迁移自身另有 `orbit_schema_migrations` 记录。
+
+| 模块 | Go 模型 | 数据表 |
+| --- | --- | --- |
+| platform | `Application` | `orbit_applications` |
+| platform | `Namespace` | `orbit_namespaces` |
+| platform | `Credential` | `orbit_credentials` |
+| platform | `IdempotencyKey` | `orbit_idempotency_keys` |
+| platform | `Event` | `orbit_events` |
+| platform | `Subscription` | `orbit_subscriptions` |
+| platform | `Delivery` | `orbit_deliveries` |
+| platform | `AuditEvent` | `orbit_audit_events` |
+| pulse | `Queue` | `pulse_queues` |
+| pulse | `ExecutionGate` | `pulse_execution_gates` |
+| pulse | `WorkerSession` | `pulse_worker_sessions` |
+| pulse | `Task` | `pulse_tasks` |
+| pulse | `Attempt` | `pulse_attempts` |
+| pulse | `AttemptReceipt` | `pulse_attempt_receipts` |
+| pulse | `ConcurrencyLimit` | `pulse_concurrency_limits` |
+| pulse | `Permit` | `pulse_permits` |
+| pulse | `Schedule` | `pulse_schedules` |
+| pulse | `ScheduleVersion` | `pulse_schedule_versions` |
+| pulse | `Occurrence` | `pulse_schedule_occurrences` |
+| weave | `Definition` | `weave_definitions` |
+| weave | `DefinitionVersion` | `weave_definition_versions` |
+| weave | `Instance` | `weave_instances` |
+| weave | `Step` | `weave_steps` |
+| weave | `Activation` | `weave_activations` |
+| weave | `Wait` | `weave_waits` |
+| weave | `Signal` | `weave_signals` |
+| weave | `PollState` | `weave_poll_states` |
+| weave | `PollRound` | `weave_poll_rounds` |
+| weave | `InboxEvent` | `weave_inbox` |
+| weave | `PendingAdvance` | `weave_pending_advances` |
+
+设计文档中的 `task_events` / `result_events` 当前合并为 `orbit_events`，通过聚合类型、事件类型和状态版本区分；对外投递使用 `orbit_deliveries`，内部流程接续使用 `weave_inbox`。`weave_pending_advances` 保存暂停或分批推进后的续接检查点。
+
+## 4. 已落实的数据库约束
+
+- 幂等身份在命名空间、操作和资源作用域内唯一；保存请求摘要和原响应。
+- 一个任务的执行代次唯一，当前尝试必须属于同命名空间、同任务。
+- 计划触发按计划与 UTC 原触发时间唯一，计划修改不会绕过触发去重。
+- 定义版本不可覆盖，实例绑定明确的版本记录。
+- 步骤属于指定实例，激活属于指定步骤；避免同租户内错接另一个流程。
+- 查询轮次与任务分别唯一；轮次、单轮尝试预算和截止时间独立保存。
+- 内部事件与外部订阅交付有去重键，租用状态要求有效租用字段。
+- 终态必须有结束时间，待执行任务不能伪造有效执行租约。
+
+## 5. 仍需服务层事务保证的条件
+
+外键与 `CHECK` 无法代替执行引擎。以下属于后续服务实现与回归目标：
+
+1. 权限验证、凭据校验、命名空间过滤和队列消费授权。
+2. 同一次事务更新任务、尝试、租约、并发许可、事件与流程交付记录。
+3. CAS 竞争、数据库时间校验、门控与开始授权串行化。
+4. 对幂等重复请求比较语义摘要，返回原响应或冲突。
+5. 计划当前版本与版本内容原子发布，信号匹配正确的业务操作。
+6. 查询轮次、预算、下一任务创建同事务提交；未知结果按证据核查。
+7. 不可变版本发布前的流程图校验、表达式类型与结构化汇合验证。
+
+当前模型方法只校验局部状态或预算，不能被当作已经实现了执行授权和业务幂等。
+
+## 6. 迁移与回归
+
+入口是 `orbit-migrate up|status`。应用进程只检查迁移状态，不执行 DDL。迁移持有数据库级命名锁，逐语句应用；失败保留 dirty 标记。由于 MySQL DDL 不整体回滚，修复必须先对照语句和实际表结构完成核查，不提供自动清除 dirty 的命令。
+
+已应用的迁移不得修改。后续使用新的前向迁移；回归环境使用独立临时数据库。初始迁移尚未在生产部署。
+
+命令与验证记录见 [开发计划](08-development-plan.md) 和 [基础阶段验证报告](reports/phase-0.md)。
--- a/docs/08-development-plan.md
+++ b/docs/08-development-plan.md
@@ -0,0 +1,74 @@
+# Orbit 持续开发与回归计划
+
+更新：2026-09-17。此计划对应持续开发目标，由开发过程同步维护。
+
+## 1. 最终交付目标
+
+交付可由多个业务项目接入的 Go + MySQL + HTTP/WebSocket 平台：Pulse 管理任务与调度，Weave 管理持久化流程，业务处理器运行在独立 Worker。研发通过独立 Go SDK 定义和发布流程。
+
+完成标准包括服务端、SDK、迁移及运行工具、Markdown 接口手册、可运行场景示例，以及实际正确性/故障/性能验证记录。完成设计、单机运行或展示一条正常路径，均不等同于完成首版交付。
+
+## 2. 持续推进方式
+
+每个阶段按以下顺序推进：
+
+1. 根据已确认功能细化状态、协议、数据及完成标准。
+2. 完成一条可执行的业务无关调用链，同步 SDK 和文档。
+3. 运行单元、真实数据库、协议及端到端回归，记录失败与修复。
+4. 验证该阶段异常路径、兼容性、授权边界与可恢复性。
+5. 更新本计划、接口实现状态、示例和验证报告，再进入下一阶段。
+
+常规技术选择和缺陷修复自主进行。只有确实缺少外部信息或涉及未获授权的操作时才请求用户介入。不能为了让目标显示完成而隐藏未实现项或跳过故障验收。
+
+## 3. 阶段清单
+
+| 阶段 | 开发内容 | 回归与完成标准 | 当前状态 |
+| --- | --- | --- | --- |
+| P0 基础与数据模型 | Go workspace、独立 SDK module、公共/Pulse/Weave 模型、MySQL 迁移、配置、健康检查 | 编译/竞态/静态检查；真实 MySQL 建表、隔离、唯一性、预算、不可变版本、迁移失败防护；SDK 健康调用 | 已完成并通过阶段回归（见 P0 报告） |
+| P1 任务受理闭环 | 应用凭据与作用域权限、队列、幂等提交、查询、待执行取消、受理事件；SDK 客户端 | API/SDK 创建查询闭环；重复键与内容冲突、响应丢失后重报、跨命名空间拒绝、参数边界 | 待开发 |
+| P2 Worker 执行闭环 | WSS 接入、能力/容量、领取与开始、租约、续租、结果确认、排空与恢复；Worker SDK | 真 Worker 执行；失联/重连/重复确认/旧尝试拒绝；业务效果未知转核查；节点故障接管 | 待开发 |
+| P3 Pulse 完整能力 | 安全重试、延时、Cron/固定间隔、漏跑策略、计划版本、并发许可、配额/背压、可靠结果订阅 | 多实例领取/触发竞争、重试上限、取消竞争、队列隔离、积压恢复、事件重复交付 | 待开发 |
+| P4 Weave 主流程 | SDK 定义构建与发布校验、实例、顺序/分支/结构化并行汇合、信号/定时等待、版本绑定 | 重启接续、早到/重复信号、并行竞争、内部事件重放、发布版本兼容；端到端通用流程 | 待开发 |
+| P5 Weave 恢复与查询 | 有界查询、暂停继续、取消、人工核查恢复、控制门控与审计 | 轮次与尝试独立预算；暂停/开始/回执/超时竞争；恢复保留预算；未知结果不盲目重复 | 待开发 |
+| P6 生产验证与运维 | 完整监控、凭据轮换、备份恢复、滚动升级、运行手册、可复现负载和故障工具 | 对照生产验收清单执行，报告环境/指标/遗留项；容量、RPO/RTO 按真实拓扑验证 | 待开发 |
+| P7 首版交付核对 | SDK 兼容与发布准备、完整 API 手册、场景示例、全量回归及交付清单 | 新接入者按文档跑通全部示例；所有首版能力可追溯到实现与测试；报告实际生产边界 | 待开发 |
+
+SDK、文档与示例随 P1–P5 同步开发，P7 是全量核对，不是最后才开始补文档。
+
+## 4. SDK 与示例交付清单
+
+| 场景 | 预期调用链 | 所属阶段 |
+| --- | --- | --- |
+| 健康检查 | 创建客户端 → 存活/就绪查询 | P0 |
+| 文件转换任务 | 提交幂等任务 → Worker 处理 → 查询结果 | P1–P2 |
+| 定期数据同步 | 发布计划 → 触发任务 → 暂停/恢复 → 查看触发记录 | P3 |
+| 并行生成结果 | 发布流程 → 并行执行 → 汇合 → 完成 | P4 |
+| 审核与外部回执 | 提交流程 → 等待信号 → 授权信号注入 → 继续 | P4 |
+| 外部作业轮询 | 提交一次 → 有界查询处理中状态 → 回执或最终结果 → 超限核查 | P5 |
+| 暂停与人工恢复 | 暂停 → 保存结果 → 核查/恢复 → 查看审计 | P5 |
+| 故障恢复 | 节点/连接中断 → 相同身份核对 → 恢复或人工核查 | P2–P6 |
+
+每个正式示例需要：前置配置、完整可运行源码、启动命令、输入、预期输出、失败路径、幂等/清理说明。SDK API 尚未实现时，文档只能标为规划，不能给出伪装可运行的代码。
+
+## 5. 回归规则
+
+- 每次模型或迁移变化：执行真实 MySQL 集成测试，验证命名空间及唯一约束。
+- 每次状态或协议变化：更新服务端、SDK、兼容说明与异常场景。
+- 每次执行/恢复变化：增加对应断线、超时、重复、迟到、宕机或竞争用例。
+- 每次发布候选：全量回归、示例回归、迁移检查、故障和负载报告。
+- 验证失败先修复再推进，未执行的项目明确记为未验证。
+
+## 6. 性能与高可用验收边界
+
+不直接用租户总数作为容量结论。P6 先固定硬件、数据库拓扑、消息大小、任务时长、连接数、峰值与积压模型，再记录受理/派发/推进/恢复的吞吐、延迟和资源消耗。
+
+本地多实例与故障注入可以验证恢复逻辑；实际生产复制确认、跨故障域部署、备份介质、RPO/RTO 及峰值余量，需要在对应部署环境复测。所有报告分别标注已验证、未验证和当前限制。
+
+## 7. 文档入口
+
+- [数据模型](07-data-model.md)
+- [接口手册](api/README.md)
+- [SDK 接入](sdk/README.md)
+- [通用场景示例](examples/README.md)
+- [生产验收总清单](05-production-acceptance.md)
+- [P0 验证记录](reports/phase-0.md)
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,82 @@
+# Orbit · 星轨设计文档
+
+- 文档版本：0.2
+- 整理日期：2026-09-17
+- 阶段：基础骨架与数据模型已实现，平台完整功能按持续计划开发；尚未完成生产验收
+- 适用范围：Orbit 统一平台，包含 Pulse 任务调度模块、Weave 流程编排模块与公共能力。平台面向多个业务系统复用。
+
+## 阅读顺序
+
+| 文档 | 内容 |
+| --- | --- |
+| [01 功能说明](01-functional-spec.md) | 平台职责、Pulse 与公共能力、操作行为与责任边界 |
+| [02 技术方案](02-technical-design.md) | 组件、部署、调度与派发、MySQL 使用方式、SDK |
+| [03 HTTP 与 WebSocket 协议](03-http-websocket-protocol.md) | 接口草案、消息结构、确认、重连、鉴权与兼容性 |
+| [04 可靠性与数据模型](04-reliability-and-data.md) | 状态机、事务、租约、幂等、调度一致性、恢复 |
+| [05 生产验收](05-production-acceptance.md) | 故障场景、性能指标、上线门槛与验证证据 |
+| [06 Weave 流程设计](06-workflow-spec.md) | 已确认的首版功能、研发定义发布、持久化等待、有界查询、暂停恢复与模块协作 |
+| [07 数据模型](07-data-model.md) | 当前 Go 实体、数据库约束、存储约定与实现边界 |
+| [08 持续开发计划](08-development-plan.md) | 开发、测试回归、阶段验收与最终交付目标 |
+| [接口手册](api/README.md) | 实际接口状态、调用说明与后续接口规划 |
+| [SDK 与场景](sdk/README.md) | 可运行示例、接入方法及分阶段 SDK 交付 |
+
+## 已确认的决策
+
+| 项目 | 决策 |
+| --- | --- |
+| 产品定位 | 通用任务调度与流程编排平台，支持多个业务项目复用 |
+| 名称与目录 | Orbit · 星轨，目录 `orbit/` |
+| 项目与部署 | 一个统一项目，内部保留 Pulse 与 Weave；平台独立于业务系统部署，业务方通过 SDK 接入 |
+| 开发语言 | Go |
+| 持久化 | MySQL 为任务、执行、计划、流程及结果的权威存储 |
+| 通信方向 | HTTP + WebSocket；生产使用 HTTPS / WSS |
+| HTTP 职责 | 任务提交、流程启动与信号、查询、计划管理、配置与管理操作 |
+| WS 职责 | Worker 接入、能力与容量上报、任务派发、续租、结果上报、取消通知 |
+| 执行位置 | 业务处理器位于业务项目自己的 Worker 中 |
+| 外部依赖范围 | 首版以 MySQL 为必需的外部存储依赖；运行不要求 Redis、独立消息队列或独立协调服务 |
+| Pulse 与公共功能范围 | 任务管理、定时计划、Worker 与恢复、资源控制、多项目权限、审计可观测、SDK 与运维 |
+| Weave 定位与定义方式 | 同一平台内承担流程编排，研发通过 Go SDK 描述并发布版本，业务处理器仍在业务 Worker 中运行 |
+| Weave 首版流程能力 | 顺序、条件分支、有限并行与汇合、等待信号、定时等待、有界重复查询 |
+| Weave 首版管理能力 | 暂停与继续、取消、人工核查与恢复、版本固定、全程追踪 |
+
+Orbit 不内置特定行业规则；Pulse 管理执行，Weave 管理步骤依赖、分支和等待等流程语义。二者通过模块接口及共享事务协作，不要求相互通过 HTTP / WS 调用。
+
+## 如何理解文档中的约束
+
+- **已确认**：上表的平台方向、Pulse 与 Weave 首版功能范围及研发定义发布方式已在讨论中确认。
+- **设计要求**：为实现已确认的生产目标提出的可靠性约束，后续代码与测试应共同遵守。
+- **设计建议 / 草案**：本次整理补充的具体实现选择，仍需协议或架构评审。
+- **待定**：没有足够依据的参数或选择，不代表已批准或已实现。
+
+本文中的“必须”描述目标行为，不代表当前已经具备该能力。示例 ID、接口与 JSON 均为设计示例。
+
+## 需要继续确认的事项
+
+| 事项 | 当前建议 / 处理方式 | 关联文档 |
+| --- | --- | --- |
+| HTTP / WS 的最终字段、路径、错误码 | 以本稿作为协议草案，评审后冻结 v1 | [协议](03-http-websocket-protocol.md) |
+| Weave 技术细则 | 功能范围已确认；SDK/定义 Schema、暂停门控与计时、查询预算、并行失败策略、人工恢复身份仍需评审 | [流程](06-workflow-spec.md) |
+| WS 库及后续依赖版本 | 当前基础使用 Go 1.27.1、MySQL 8.4+ 与显式 SQL；WS 库随 P2 实现锁定 | [模型基线](07-data-model.md) |
+| 人工重试的任务身份 | 建议创建关联的新任务，自动重试保持原任务 ID | [功能](01-functional-spec.md) |
+| Cron、固定间隔与夏令时细节 | 建议五段 Cron、固定间隔首版采用 fixed-rate；夏令时行为需明确 | [功能](01-functional-spec.md) |
+| 批量大小、消息上限、心跳、租约、扫描周期 | 均需设置有限上限；数值通过原型与压测确定 | [验收](05-production-acceptance.md) |
+| 幂等、事件、审计的保留周期 | 按恢复与业务追溯要求确定，不能仅随任务清理 | [数据](04-reliability-and-data.md) |
+| 数据库高可用与恢复目标 | 明确故障模型、复制确认、RPO / RTO 及运维责任 | [验收](05-production-acceptance.md) |
+| 容量与可用性目标 | 根据峰值提交、活跃任务、连接数和积压建立负载模型 | [验收](05-production-acceptance.md) |
+| 多分区与全局配额细节 | 明确路由与配额一致性范围后实现，首版不承诺跨库原子操作 | [技术](02-technical-design.md) |
+
+上述事项中影响执行安全、兼容和容量验收的内容，必须在生产发布前关闭。不能将“待定”参数直接作为生产默认值。
+
+## 文档维护规则
+
+1. 功能文档定义使用者看到的行为；协议文档定义通信；数据文档定义权威状态与不变量，其他文档通过链接引用。
+2. 修改状态、幂等、重试、租约或确认语义时，同时更新协议、恢复场景和验收项。
+3. 改变已确认决策时记录原因、影响与迁移方式，不静默替换旧约定。
+4. 设计建议不应被描述为已验证的性能或生产保证。
+5. 当前已在 Orbit 目录初始化独立 Git 并开始代码实现；服务端、SDK、文档与测试同步维护，不修改目录外的历史项目。
+
+## 决策更新
+
+2026-09-17，文档更新至 0.2：用户确认研发定义发布流程及 Weave 首版功能，明确纳入有界重复查询和暂停/继续等生产管理能力。技术细则与参数继续按建议或待定标注，未将功能确认等同于实现或验收通过。
+
+持续开发目标已建立。当前实现和验收进度以 [开发计划](08-development-plan.md) 与 [验证报告](reports/phase-0.md) 为准；早期设计稿中的“未实现”描述保留其编写阶段语境。
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -0,0 +1,34 @@
+# Orbit HTTP / WebSocket 接口手册
+
+更新：2026-09-17。接口实现状态随 [开发计划](../08-development-plan.md) 更新。
+
+## 当前接口状态
+
+| 接口 | 状态 | 手册 |
+| --- | --- | --- |
+| `GET /health/live` | 已实现 | [健康检查](health.md) |
+| `GET /health/ready` | 已实现，仅验证数据库与迁移记录 | [健康检查](health.md) |
+| `/v1/tasks` 与任务管理 | 计划 P1–P3，尚未实现 | [任务接口规划](tasks.md) |
+| `/v1/worker/connect` | 计划 P2，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
+| `/v1/schedules` 与计划管理 | 计划 P3，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
+| `/v1/events/connect` | 计划 P3，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
+| `/v1/workflows` 与流程管理 | 计划 P4–P5，尚未实现 | [流程接口规划](workflows.md) |
+
+当前服务对未实现路由返回 404。健康检查就绪不表示任务调度、鉴权或流程引擎已经可用。
+
+## 业务接口统一要求
+
+下述业务契约尚在实现阶段细化，不能用于声称当前已有业务 API：
+
+- 生产使用 HTTPS/WSS，凭据通过授权头或受控握手传递，不放入 URL。
+- 应用身份、命名空间和操作权限分别校验；知道资源 ID 不等于拥有权限。
+- 稳定幂等键与请求追踪 ID 分开；超时重报保留原键。
+- 可能超过跨语言整数精度的 ID 和执行代次使用字符串。
+- 时间为 UTC RFC 3339，时长字段带单位；查询和批量操作有上限。
+- 错误码、字段、分页游标和限制值在对应阶段实现及回归后冻结。
+
+健康接口目前直接返回状态对象。业务接口计划使用 `request_id` + `data` / `error` 信封，详见 [通信协议](../03-http-websocket-protocol.md)。
+
+## 每个正式接口的文档模板
+
+实现时必须补齐：用途与权限、HTTP 方法和路径、请求头、字段类型/必填/默认值/限制、完整请求与响应、错误码、幂等与并发规则、超时/重试/取消语义、SDK 对应方法、可运行示例、兼容版本和已覆盖的回归场景。
--- a/docs/api/health.md
+++ b/docs/api/health.md
@@ -0,0 +1,45 @@
+# 健康检查接口
+
+状态：已实现，基础阶段。无需鉴权；默认仅监听 `127.0.0.1:8080`。
+
+## GET /health/live
+
+返回进程 HTTP 服务是否存活，不访问数据库。
+
+```sh
+curl -i http://127.0.0.1:8080/health/live
+```
+
+HTTP 200，`Content-Type: application/json`：
+
+```json
+{"status":"alive"}
+```
+
+## GET /health/ready
+
+检查数据库连接和迁移记录是否与当前二进制的版本、校验和一致且没有 dirty 标记。内部检查最多 2 秒。
+
+```sh
+curl -i http://127.0.0.1:8080/health/ready
+```
+
+通过时 HTTP 200：
+
+```json
+{"status":"ready","scope":"database_and_schema"}
+```
+
+数据库不可用、迁移缺失、记录被修改或存在 dirty 标记时 HTTP 503：
+
+```json
+{"status":"not_ready"}
+```
+
+响应不包含 DSN、数据库错误文本或凭据。检查迁移记录不能发现所有人工 DDL 漂移，运行账户权限和迁移流程仍需受控。
+
+## SDK 与运行限制
+
+对应 `Client.Liveness(ctx)` 和 `Client.Readiness(ctx)`，见 [SDK 接入](../sdk/README.md)。HTTP 503 返回 `*orbit.HTTPError`。
+
+此阶段的 ready 只表示数据库与迁移基础可用；尚无任务、Worker、流程或业务鉴权服务。SDK 默认请求超时为 10 秒，调用方可通过 context 设置更短期限。
--- a/docs/api/tasks.md
+++ b/docs/api/tasks.md
@@ -0,0 +1,16 @@
+# 任务接口规划
+
+状态：计划 P1–P3，尚未实现。以下为后续落地清单；实际字段与可运行请求将在相应阶段补齐。
+
+| 操作 | 候选接口 | 关键行为 |
+| --- | --- | --- |
+| 提交 | `POST /v1/tasks` | 携带稳定 `Idempotency-Key`，受理提交完成后响应 |
+| 批量提交 | `POST /v1/tasks:batchSubmit` | 每项独立幂等与结果；顶层成功不代表全部成功 |
+| 查询 | `GET /v1/tasks/{task_id}` | 校验命名空间和权限，返回当前状态与结果 |
+| 执行历史 | `GET /v1/tasks/{task_id}/attempts` | 分页返回历史尝试，不展示执行秘密凭据 |
+| 取消 | `POST /v1/tasks/{task_id}:cancel` | 待执行时取消生效；在途工作先记录取消意图 |
+| 人工重试 | `POST /v1/tasks/{task_id}:retry` | 带原因与权限；流程关联任务通过 Weave 恢复 |
+
+提交契约需要队列、处理器/参数版本、业务输入或引用、执行时间、时限、恢复安全等级和重试策略。业务参数内容由接入方解释。
+
+P1 回归完成前，此页不提供看似可调用的 SDK 方法或 HTTP 请求体。接口实现后同步增加完整请求/响应、错误码及文件转换场景。
--- a/docs/api/workflows.md
+++ b/docs/api/workflows.md
@@ -0,0 +1,16 @@
+# 流程接口规划
+
+状态：计划 P4–P5，尚未实现。研发通过 Go SDK 描述流程并显式发布，服务端保存不可变定义版本。
+
+| 操作 | 候选接口 | 完成要求 |
+| --- | --- | --- |
+| 发布版本 | `POST /v1/workflow-definitions/{definition_id}/versions` | 图结构、类型、预算校验；同版本同内容幂等，不同内容冲突 |
+| 启动实例 | `POST /v1/workflows` | 固定版本并幂等启动，首批任务与实例原子创建 |
+| 查询实例 | `GET /v1/workflows/{workflow_id}` | 状态、暂停标记、版本、等待原因、预算摘要 |
+| 查询步骤 | `GET /v1/workflows/{workflow_id}/steps` | 步骤、激活、查询轮次、输入/结果引用与任务关联 |
+| 提交信号 | `POST /v1/workflows/{workflow_id}/signals` | 幂等、授权、业务操作匹配；受理与消费分别可查 |
+| 暂停/继续 | `POST /v1/workflows/{workflow_id}:pause`、`:resume` | 控制版本与门控原子变化，保留进度、预算与审计 |
+| 取消 | `POST /v1/workflows/{workflow_id}:cancel` | 停止后续工作，收集在途结果，不伪装业务撤销 |
+| 核查恢复 | 具体接口待实现阶段冻结 | 权限、证据、预期版本与稳定操作身份；保留旧激活历史 |
+
+配套场景：并行生成结果、等待审核信号、外部作业有界查询、暂停与核查恢复。正式示例将在对应 API 和 SDK 通过端到端验证后提供。节点与状态设计见 [Weave 功能与设计](../06-workflow-spec.md)。
--- a/docs/examples/README.md
+++ b/docs/examples/README.md
@@ -0,0 +1,24 @@
+# 通用场景示例
+
+示例只使用通用的作业、对象、文件、资源与审核信号，不包含接入方项目名称或行业规则。
+
+## 已可运行：健康检查
+
+- 源码：[SDK 健康检查](../../sdk/go/examples/health/main.go)。
+- 前置：已迁移的 MySQL 与已启动的基础服务。
+- 操作与预期输出：[SDK 接入说明](../sdk/README.md)。
+- 异常：数据库不可用或迁移记录异常时 readiness 返回 HTTP 503，SDK 返回类型化状态错误。
+- 清理：只读调用，无业务资源需要删除。
+
+## 计划场景与验收标准
+
+| 场景 | 输入与步骤 | 预期结果 | 必测异常 | 状态 |
+| --- | --- | --- | --- | --- |
+| 文件转换 | 对象引用 → 提交任务 → Worker 转换 → 结果引用 | 同一操作获得一次业务结果，历史可查 | 重复提交、Worker 在结果上报前中断 | P1–P2 待开发 |
+| 定期同步 | 发布计划 → 周期触发 → 暂停 → 恢复 | 触发身份唯一，漏跑策略可追溯 | 多节点竞争、停机后补跑上限 | P3 待开发 |
+| 并行生成 | 输入对象 → 并行计算两份结果 → 汇合 | 两支满足条件后只创建一份后继工作 | 一支失败、重复结果、汇合竞争 | P4 待开发 |
+| 等待审核 | 校验 → 等待信号 → 发布结果 | 只接受授权、匹配当前操作的信号 | 早到、重复、过期与越权信号 | P4 待开发 |
+| 外部作业查询 | 提交一次 → 间隔查询 → 最终结果 | 处理中消耗轮次，请求失败消耗尝试 | 回执与查询竞争、预算耗尽、响应未知 | P5 待开发 |
+| 暂停与恢复 | 暂停 → 接收在途结果 → 核查 → 继续 | 历史与预算保留，已成功工作不重复 | 暂停/开始竞争、恢复时已过期 | P5 待开发 |
+
+每个待开发场景最终都需提供独立目录、完整源码、配置模板、启动与验证命令，不能只留下概念流程图。配套回归会先使用可控的模拟处理器或外部服务，不对真实系统产生副作用。
--- a/docs/reports/phase-0.md
+++ b/docs/reports/phase-0.md
@@ -0,0 +1,51 @@
+# P0 基础阶段验证记录
+
+日期：2026-09-17。范围：数据模型、MySQL 迁移、基础 HTTP 与 SDK 健康调用。
+
+## 环境
+
+- macOS arm64，Go 1.27.1 官方工具链，下载摘要已核对。
+- MySQL 8.4.10，Docker 独立临时容器；随机凭据、回环随机端口，测试结束后删除容器。
+- MySQL 驱动 `github.com/go-sql-driver/mysql v1.10.1`，依赖版本记录于 go.mod/go.sum。
+- 使用真实 MySQL，不以 Mock 代替迁移或数据库约束验证。
+
+## 验证结果
+
+| 项目 | 结果 |
+| --- | --- |
+| 服务端编译 | 已通过 |
+| 服务端 `go test -race ./...` | 已通过 |
+| 服务端 `go vet ./...` | 已通过 |
+| 两个迁移调用竞争同一数据库锁 | 已通过 |
+| 30 个模型与实际数据库列名一致性 | 已通过 |
+| 跨命名空间关联拒绝 | 已通过 |
+| 非法任务状态、缺少租约与超尝试预算拒绝 | 已通过 |
+| 本地事务回滚 | 已通过 |
+| 幂等键作用域与唯一约束 | 已通过 |
+| 流程发布版本不可修改 | 已通过 |
+| 查询轮次、任务唯一性与预算约束 | 已通过 |
+| 状态事件与审计记录不可改写 | 已通过 |
+| dirty 迁移与校验和漂移阻断 | 已通过 |
+| SDK HTTP 契约与错误边界 | 已通过 |
+| 迁移 CLI → 真实服务 → SDK 健康示例 | 已通过 |
+| 文档链接、示例与接入方标识清理 | 已通过 |
+| 模型与数据库中文注释 | 30 个模型的持久化字段及 30 张表、366 个列注释已补齐，DDL 再次验证通过 |
+
+数据库集成用例首轮约 7.37 秒，最终复核约 2.12 秒，中文注释补齐后再验证约 1.91 秒；这只是功能测试耗时，不是容量基准。最终端到端输出为 `liveness=alive readiness=ready scope=database_and_schema`。
+
+文档检查覆盖基础阶段 17 个 Markdown 文件（随后新增 AGENTS.md 维护中文注释规范）、69 个本地链接和 4 个 JSON 示例，未发现失效链接或接入方定制标识。
+
+## 复现
+
+```sh
+make test
+make vet
+make build
+make integration
+```
+
+普通 `go test` 会跳过需要数据库的测试；`make integration` 会创建专用数据库、运行实际约束测试，并启动真实服务执行 SDK 示例。显式设置 `ORBIT_TEST_MYSQL_DSN` 直接运行测试时，必须使用可丢弃的独立数据库。
+
+## 未验证范围
+
+目前没有任务处理器、Worker 协议、调度或流程执行引擎，不宣称这些能力已通过验收。尚未执行生产吞吐、长稳、多节点调度、数据库高可用、备份恢复和真实业务接入验收。这些内容在后续阶段实现并验证。
--- a/docs/sdk/README.md
+++ b/docs/sdk/README.md
@@ -0,0 +1,72 @@
+# Go SDK 接入说明
+
+当前已实现客户端创建、存活与就绪查询。任务提交、Worker 和流程构建接口按开发计划逐阶段实现。
+
+SDK module：`git.yuntuo.hk/k2safe/orbit/sdk/go`。服务端与 SDK 在同一 Git 仓库，使用独立 `go.mod`；SDK 当前仅依赖 Go 标准库。
+
+## 1. 本地运行当前示例
+
+前置条件：Go 1.27.1、MySQL 8.4+，先按项目根目录 README 迁移数据库并启动服务。
+
+在仓库根目录执行：
+
+```sh
+cd sdk/go
+ORBIT_URL=http://127.0.0.1:8080 go run ./examples/health
+```
+
+期望输出：
+
+```text
+liveness=alive readiness=ready scope=database_and_schema
+```
+
+[完整示例源码](../../sdk/go/examples/health/main.go)。示例 context 最多等待 5 秒；数据库或迁移未就绪时返回错误并以非零状态退出。
+
+## 2. 当前真实调用方式
+
+```go
+client, err := orbit.NewClient("http://127.0.0.1:8080", orbit.Options{})
+if err != nil {
+    return err
+}
+
+ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+defer cancel()
+
+health, err := client.Readiness(ctx)
+if err != nil {
+    var responseErr *orbit.HTTPError
+    if errors.As(err, &responseErr) {
+        // responseErr.StatusCode 是实际 HTTP 状态，例如 503。
+    }
+    return err
+}
+fmt.Println(health.Status, health.Scope)
+```
+
+片段需在调用函数中使用并导入标准库包和 `orbit`；完整可运行程序见上方源码。
+
+`Options.HTTPClient` 可注入专用 HTTP 客户端。SDK 复制其配置，不修改调用方客户端；禁止自动跟随重定向，限制健康响应大小，不自动重试请求，不将服务端响应正文放进错误。
+
+## 3. 外部项目的本地接入
+
+仓库尚未发布 SDK 版本。开发期间可使用独立工作区或本地 replace，例如在接入项目中执行：
+
+```sh
+go mod edit -require=git.yuntuo.hk/k2safe/orbit/sdk/go@v0.0.0
+go mod edit -replace=git.yuntuo.hk/k2safe/orbit/sdk/go=/absolute/path/to/orbit/sdk/go
+go mod tidy
+```
+
+示例路径需替换为本机实际目录。不要将本机绝对路径 replace 提交为发布依赖。后续发布 SDK 时使用独立 module 标签与兼容说明，在真实仓库取包路径验证后给出 `go get` 命令；当前不提供不存在的发行版本。
+
+## 4. 后续 SDK 交付
+
+- P1：凭据配置、幂等提交、查询与待执行取消。
+- P2：处理器注册、Worker 容量、WSS、续租与结果确认、优雅退出。
+- P3：计划管理、可靠结果订阅与队列控制。
+- P4：流程定义、发布、启动、信号与查询。
+- P5：有界查询、暂停继续和人工恢复入口。
+
+每阶段同步更新可运行场景、错误处理与兼容测试。业务幂等、外部结果核查与 Outbox 接入责任会与真实代码示例一起说明。