ADR-010：Hermes 在线生命周期使用默认关闭的内部 Runtime API

状态：Accepted for Release Candidate
日期：2026-07-21
范围：AIOS V2R1 Hermes Worker Lifecycle Acceptance

决策

使用现有 HermesAdapter Queue/Lease 状态机，增加 SQLite 持久 Store，并通过默认关闭的内部 Runtime API 执行 Claim、Start、Heartbeat、Complete、Fail、Cancel 与 Status。不建立第二套 Queue、Lease 或 Task 状态机。

内部 API 只接受可信代理注入且具有 runtime/platform_admin 角色的身份。请求必须绑定 tenant、task、trace、principal、provenance、run、dispatch、job、cell 和 profile。 Complete、Fail、Cancel 只能经 ExecutionOrchestrator.reconcile_hermes 更新权威 Task。

背景

原 Candidate 已具有进程内 Hermes Claim/Lease/Worker 能力及持久 Dispatch，但在线服务只暴露 enqueue/reconcile，且 Hermes Job/Lease 本身在重启后丢失，不能形成完整在线证据。

原因

直接验收驱动会形成 Adapter 之外的额外变更入口，难以证明 HTTP 身份、Dispatch 与 Orchestrator 边界。受保护的内部 API 可以在真实 localhost 服务、真实 SQLite Store 和真实 HTTP 解析路径上验证完整生命周期，同时在生产通过配置保持关闭。

备选方案

受信验收驱动直接导入 Adapter：改动较小，但不能证明内部 HTTP 身份与请求解析边界，拒绝。
新建独立 Queue/Lease 服务：会产生第二状态机和双写一致性问题，禁止。
开放公共 Worker API：扩大攻击面并允许浏览器/Operator 触发 Runtime 状态，禁止。

安全不变量

只有 APPROVED Task 可由 Orchestrator 创建 Hermes Job。
Dispatch 在 Runtime 副作用前持久化。
Worker 只能操作精确绑定且由其持有 Lease 的 Job。
Runtime 结果必须通过完整身份元组与持久 Dispatch 校验。
只有 Orchestrator 能把 Task/Dispatch 推进到 Runtime 终态。
生命周期写入同步生成 Audit/Event 与 Execution Evidence。
相同终态重放幂等，不同终态或不同内容 fail closed。

恢复语义

SQLiteHermesStore 持久保存 Job、Result、Lease、幂等键与 Worker heartbeat。服务重启加载同一状态；过期 Lease 被持久重排为 QUEUED，清理旧 Owner 并递增 revision。新 Worker 可重领，旧 Worker 的 Start/Heartbeat/Result 被拒绝。

影响与风险

正面：同一 Adapter 状态机获得持久恢复、真实 HTTP 验收、严格身份绑定和可审计证据。
负面：SQLite Snapshot 每次生命周期变更都执行同步事务，需在预生产观察锁等待与吞吐。
风险：可信代理头是身份边界；因此接口必须保持 localhost/内部路由、默认关闭，并由部署配置保证外部请求不能自行注入身份头。

迁移与回滚

新 Store 文件为新增的 hermes.sqlite3，不修改既有 Control Plane/Dispatch schema。回滚到 Previous OID 时保留该文件但旧版本不读取；不得用旧备份覆盖新业务状态。重新升级时可继续加载。接口回滚只需关闭环境开关并恢复 Previous Release OID。

合规检查

不修改 main，不创建 Tag，不绕过 Provenance/Grant。
生产默认关闭生命周期验收入口。
Secret 不进入请求、Audit、Evidence 或测试数据。
Result 由 Orchestrator 与持久 Dispatch 校验，负向场景 fail closed。

受影响资产

代码：aios_hermes/adapter.py、aios_v2/app.py、orchestrator.py、gateway.py。
测试：test_hermes_live_lifecycle.py 及 Candidate/Provenance 回归。
文档：用户需求、模块合同、追踪矩阵、Gate A 报告与本 ADR。

验证

tests/aios_v2_candidate/test_hermes_live_lifecycle.py 通过真实 localhost HTTP Server 与临时 SQLite 状态目录覆盖 17 项正向、负向、Lease、幂等和重启场景。最终发布结论仍必须以提交后的 Gate、在线回归、Secret Audit、SQLite 检查、回滚与独立 Reviewer 证据为准。

4.0 KiB Raw Blame History