spec: define semantic runner recovery contract

2026-07-20 06:24:08 +02:00
parent 81f02824a4
commit f66f651deb
4 changed files with 32 additions and 2 deletions
@@ -252,6 +252,16 @@ AgentRun核心应提供 manager boot/background reconciler，从 Postgres active

 stale lease 不能单独推断 runner lost。runner lost、still running、completed pending terminal report、terminal committed 和 unrecoverable blocker 必须由 heartbeat、Kubernetes phase、runner job identity、terminal report state 和受控时间窗口共同判定，并由 AgentRun 写侧收敛。HWLAB、Web、CLI、result renderer 和 Workbench GET 只能消费这些 durable facts 和 diagnostics。

+runner 启动和 backend 执行故障必须由 manager/reconciler 统一归类并写入 durable event ledger。故障事件至少包含以下字段：
+
+- `failureDomain=upstream|infrastructure`、`component`、`code` 和脱敏后的 `summary`；
+- `retryable`、`attempt`、`maxAttempts`、`backoffMs` 和 `nextRetryAt`；
+- `firstObservedAt`、`observedAt`、`runId`、`commandId`、`runnerJobId` 和 `traceId`。
+
+有限重试必须形成 `failureObserved`、`retryScheduled`、`retryStarted`、`retryRecovered` 和 `retryExhausted` 等可回放阶段，字段命名可等价但语义不得合并。manager/reconciler 是执行生命周期和重试状态的唯一写侧；Kubernetes kubelet 或 backend adapter 可以执行具体恢复动作，但不得建立第二套重试计数、终态或用户可见状态。
+
+重试策略属于核心执行配置，必须由 owning YAML 声明基础退让、倍数、最大退让、最大次数或总截止时间以及 jitter。连接拒绝、临时 DNS、超时和上游 `5xx` 等瞬时故障可以指数退让；镜像不存在、鉴权拒绝、非法镜像名和缺失必需 Secret 等确定性故障必须立即形成不可重试终态。重试耗尽必须在策略窗口内结束 command/run，禁止继续依赖通用 retention 或 stale GC 让用户长时间停留在无解释的 running 状态。
+
 ### 6.7 AR-CORE-REQ-007 runner terminal durable outbox

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -135,6 +135,8 @@ HWLAB 接入必须按 AgentRun Kafka event cursor 幂等消费并 direct publish

 AgentRun manager rolling 或 runner terminal report delayed 时，HWLAB接入只能消费 AgentRun durable diagnosis、observation facts 和 terminalReportState，并把它们交给 Workbench projection diagnostic。若 AgentRun ledger 暂时 stale、runnerJob observation 尚未恢复或 terminal outbox 尚未提交，HWLAB 应输出 projecting/degraded/stalled/blocker 等可解释状态；不得在 dispatcher、compat wrapper、GET handler、CLI renderer、trace polling 或 Web reducer 中根据 Kubernetes Job phase、stdout、最后一条 event、elapsed timeout 或用户切换 session 推断 completed。

+AgentRun 的 `failureObserved`、`retryScheduled`、`retryStarted`、`retryRecovered` 和 `retryExhausted` 必须由 mapper 无损转换为 `hwlab.event.v1`。映射至少保留故障域、组件、代码、脱敏摘要、可重试性、当前与最大次数、退让时长、下次重试时间、首次观察时间和执行标识。HWLAB 不得重新分类故障、重置重试计数、安排重试或从 elapsed time 推断耗尽。
+
 同一次用户提交、steer 或 retry 应在 admission 时生成稳定 turnId、traceId、userMessageId 和 assistantMessageId。初发 UI 可以基于这些标识做 optimistic 展示；AgentRun events/result 到达后必须用同 ID 确认或更新对应 message/part/turn/trace，而不是创建另一条会话消息。页面刷新、session 切换、SSE 重连和 CLI inspect/result 都必须恢复同一组标识和同一语义结果。

 ### 6.4 AR-HWLAB-REQ-004 HWPOD Runtime Context
@@ -51,6 +51,7 @@ PostgreSQL 可以保存查询优化所需的派生读模型，但不是 `agentru
 - 同一 Cloud API 进程从 Kafka retention 构建并由共享 live fanout 更新的有界
  session 查询索引。
 - 首次进入、刷新、切页和重连使用同一 Kafka retention→live SSE 重建 session、message、turn、terminal、Final Response 和 Trace 主状态。
+- 上游或基础设施故障、有限重试进度、恢复和耗尽通过同一 Kafka retention→live SSE 重建并持续更新。
 - 前端 reducer/adapter 的事件去重、顺序、detail-only rejection 和 diagnostic 输出。
 - 自动恢复、SSE error、cursor gap、cross-tab projection signal 和 refresh/reconnect 的允许动作与禁止动作。
 - fake SSE 单步调试页、fixture 来源、调试子标签页、请求禁用规则、可视化证据和 Playwright 回归口径。
@@ -75,6 +76,8 @@ PostgreSQL 可以保存查询优化所需的派生读模型，但不是 `agentru
 | 多源补洞 | 前端在 automatic recovery 中同时或顺序调用 `/turns`、`/sessions/:id/messages`、`/traces/:id/events`、旧 `/v1/agent/*` 等端点来推断 terminal/final/message/session 主状态。该模式禁止。 |
 | detail-only | 只服务 Trace detail、历史页、诊断和审计的 payload。它可以展示过程，不能覆盖主 message/finalResponse/turn/session authority。 |
 | terminal event | 在同一 `hwlab.event.v1` 顺序中写入 message terminal status、turn terminal、Final Response、timing 和 session running=false 的业务事件；它与其他业务事件使用同一路径，不建立第二种状态权威。 |
+| 语义故障事件 | AgentRun 写入并经 mapper 无损投影的上游或基础设施故障事实，包含组件、代码、脱敏摘要、可重试性和执行标识。 |
+| 重试阶段事件 | 同一事件流中的重试安排、开始、恢复和耗尽事实，包含当前与最大次数、退让时长和下次重试时间。 |
 | cross-page convergence | control page、observer page、刷新页和多标签页在同一 Kafka retention/live SSE 输入下收敛到同一 message count、trace ids、turn status 和 Final Response digest。 |
 | 单步调试工作台 | Cloud Web 内的独立调试路由，用 fake fixture 逐条喂入 Kafka SSE typed event，展示 reducer 决策和 UI 投影，不访问真实 Workbench mutation。 |

@@ -203,6 +206,7 @@ fake 数据优先来自真实受控样本脱敏后的 fixture。合成 fixture
 - 自动恢复路径只允许 live/replay `SSE typed event` 或 diagnostic；不得出现 `/v1/workbench/sync`、旧 `/turns`、`/sessions/:id/messages`、`/traces/:id/events` automatic fan-out 写主状态。
 - 首次进入、刷新和切页不得用 session list/detail/messages、turn、trace 或 result HTTP 响应初始化或修改主状态。
 - 前端主状态代码不得保留 HTTP 快照与 Kafka SSE 之间的优先级、sealed guard 或 merge 仲裁。
+- 前端只格式化故障和重试事件，不得自行分类、计数、调度重试或按 elapsed time 推断耗尽。
 - `traceHydration*` 命名和运行时口径必须收敛为 `traceDetail*` 或显式 detail read；旧配置字段如保留，只能作为 deprecated alias。
 - 非 `hwlab.event.v1` 业务输入以及 `detailProjection=true`、
  `authority=trace-detail-only` 的输入必须被 reducer 拒绝写主状态，
@@ -218,6 +222,8 @@ fake 数据优先来自真实受控样本脱敏后的 fixture。合成 fixture
 - refresh/reconnect/cross-tab signal 后，control/observer/fresh page 不出现 persistent `cross-page-projection-divergence`。
 - `workbench-automatic-recovery-fanout-authority`、旧 agent read-through 和旧 Workbench detail fan-out 不回归。
 - fake SSE 单步调试可以在无真实 API、无 `/sync`、无补洞的模式下从空 store 完成 session、message、terminal、Final Response、detail-only rejection 和两页收敛测试。
+- L0 从空 store 重放故障和重试 fixture 后，必须显示故障域、组件、代码、当前与最大次数以及下次重试时间；恢复或耗尽必须由对应事件收敛。
+- L1 遇到可重试基础设施故障时，必须在策略窗口内显示有限指数退让进度；恢复后继续执行，耗尽后显示语义化终态，不能停留在无解释的 running。
 - Cloud API 在 Workbench 数据库 schema 缺失或读模型迁移未完成时仍能启动，并继续 direct publish、live SSE 与 Kafka retention replay；退化项只形成可见 warning/diagnostic。
 - 同一 session 首次索引查询与后续命中必须返回相同顺序和 transport identity；
  索引未就绪、溢出或重建失败时原 retention 扫描仍可完成核心回放。