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；事件消费SDK、可运行Inbox示例和真实订阅进程故障回归完成前，不标记P3订阅能力完成。