orbit/AGENTS.md

Orbit 开发约定

• Orbit 是通用平台。代码、文档和示例不得包含接入方项目名称或行业定制规则。

• 服务端分为公共能力、Pulse 与 Weave；SDK 是独立 Go module，不引用服务端模型或存储实现。

• 新增或修改数据模型必须提供中文注释，覆盖模型职责及每个持久化字段的含义。明确单位、可空语义、版本/幂等/租约/预算等约束，避免仅重复字段名。

• SQL 数据表和字段同步维护中文 COMMENT；已应用的迁移不得回改，后续演进新增前向迁移。

• 数据库禁止外键及级联删除。关联关系由服务端在同一事务中按命名空间校验；保留查询索引、唯一约束和 CHECK。历史外键由 000008 前向移除，后续迁移不得重新引入，真实 MySQL 回归必须断言外键为 0。

• Pulse 涉及用量的事务先锁应用额度再锁队列，恢复和调度遵守同一顺序；不得在已锁队列后新增应用额度锁。应用额度与身份行分离，不能升级认证共享锁。

• 优先级冻结为 0–9，每级30秒排序优势；dispatch_at 是数据库生成排序字段，不能替代 available_at 的实际就绪检查。节点按认证应用与队列轮转领取，内存轮转/空探测缓存不得授予执行权或改变持久化配额。

• 状态变更、租约、门控、许可、事件及审计必须按设计的事务边界实现，不用内存状态代替持久化确认。

• 研发任务持续更新 docs/08-development-plan.md。接口、SDK、可运行示例和对应回归随功能同步交付。

• 模型/迁移变更运行真实 MySQL 集成测试；执行和恢复变更覆盖竞争、重复、迟到及故障场景。以实际测试报告判断完成，不把设计文档当作已实现能力。

• 编译和基础回归入口是 make test、make vet、make build；隔离数据库端到端回归入口是 make integration。

• 结果日志的序号在独立命名空间流行锁下分配，与任务状态及原事件同事务提交；禁止用最大事件ID或时间戳推断提交水位。生产者不得锁订阅行。

• 创建订阅先锁队列再锁流行；消费按订阅→交付持锁，不能再取得任务、队列、额度或流行锁。ACK只验证最近代次及证明，过期未被替代的证明仍可确认；重复确认不能再次扣减pending_count。

• 可靠订阅已完成核心、HTTP/WSS、管理及消费SDK、独立业务Inbox示例、节点及消费者进程故障回归。批量受理已提供逐项幂等与未知结果分类。独立任务核查/人工重试已实现，任务查询已支持业务键、创建时间及直接来源（普通/人工重试/计划固定版本），业务事务Outbox独立示例已实现并通过全量链路回归；P3已完成原功能范围核对与全量阶段回归（docs/reports/phase-3.md），相对延迟及四种重试全停恢复一并验证；继续P4–P7，保留精确A04故障、生产验证和实际文件转换示例等未完成项，不能把P3阶段验收当作全平台交付。

• 批量受理最多32项、512 KiB；每项复用单项身份与事务，未知结果必须原键核对。任务提交按认证→应用额度→提交幂等身份→队列持锁，禁止恢复为先抢提交唯一键后等待额度锁；原回执仍须先于配额上限检查返回。

• 独立任务核查必须显式声明所有历史执行已结束，并提交原因、证据和版本；NEEDS_REVIEW只转SUCCEEDED/FAILED。核查不改写旧尝试或迟到证据。人工重试仅无所有者且无未知效果的FAILED/CANCELLED任务，创建retry_of关联新任务，每个原任务最多一个直接后继；继续重试沿后继推进。

• tasks:review、tasks:retry、tasks:audit:read是显式管理权限，普通提交/Worker凭据不自动获得。核查结果流锁最后获取，审计/回执/额度与状态同事务；恢复不得绕过Weave/计划所有权、门控及现有额度限制。

• 任务列表队列必填，business_key精确匹配（包含尾部空格），created_from包含/created_before不包含。v2游标绑定所有筛选，不能因网络或游标错误删筛选降级；旧游标仅兼容旧查询。四种固定索引覆盖状态/业务键组合，禁止全量取回后内存过滤。业务键仅Go空字符串映射NULL。

• 任务来源通过独立只读路由查询，tasks:read仅授予当前任务的有限来源引用；计划定义仍需schedules:read。显式核对命名空间、队列、计划、触发与固定版本，悬空/错误/未实现所有者不得默认为DIRECT；不依赖外键，也不向派发路径加入来源查询。

• 业务事务Outbox示例使用独立module和业务数据库，核心SDK不得引入SQL驱动。业务记录/待发命令同事务；原请求、操作ID、目标及提交键冻结，HTTP在事务外，确认按最新租约代次与业务关联同事务。24小时/100次预算内原键核对，禁止换键、重置预算或把ACCEPTED解释成业务成功；REVIEW保留待核查数据。

• 相对延迟delay_ms只在首次受理事务按数据库时间计算；原时长参与摘要，零值omitempty保持旧摘要。重报先返回原回执，禁止重算执行时间；总时限包含等待。计划模板拒绝非零delay_ms，人工重试不自动继承首次等待。