错误、幂等与 SSE

Problem details

非 2xx 响应使用 application/problem+json：

{
  "type": "about:blank",
  "title": "Quota Exceeded",
  "status": 429,
  "detail": "tenant queued-run quota exceeded",
  "code": "quota_exceeded",
  "request_id": "01J...",
  "retryable": true
}

常见稳定码包括 idempotency_conflict、quota_exceeded、join_timeout 以及由 schema、认证、并发和资源状态映射的 problem code。错误码新增时客户端应安全地归入未知错误，而不是失败解析。

Steering 相关错误码

Run 业务错误

创建 run 成功返回 202 pending。之后的节点/schema/provider 错误会使资源变为 failed、timed_out 或 dead_letter，并写入：

{
  "status": "failed",
  "error": {
    "code": "invalid_update",
    "message": "...",
    "retryable": false
  }
}

查询和 join 请求本身仍可返回 200。客户端必须同时检查 HTTP 状态与 run.status。

SSE 格式与续传

GET /v1/runs/{run_id}/stream
Accept: text/event-stream
Last-Event-ID: 17

id: 18
event: node_completed
data: {"id":"...","run_id":"...","sequence":18,"kind":"node_completed","data":{},"created_at":"..."}

• 事件在发送前写入 PostgreSQL；
• sequence 在 run 内从 1 单调递增；
• 重连时发送最后已处理的 Last-Event-ID，服务端从下一条继续；
• 客户端按 (run_id, sequence) 去重，处理重复交付；
• 以 : heartbeat 开头的行是保活注释，应忽略；
• run 到达 terminal 或 paused 后，服务端关闭流。

Steering 生命周期事件

除了图执行过程中产生的普通事件（node_completed 等），运行中输入（steering）在其生命周期 中会产生三类专门的 SSE 事件：

run.steer.superseded 的 unconsumed_at_final_boundary 原因是一个刻意保持诚实、笼统的 标签——它并不声称该事件在与什么竞争。它涵盖了 worker 到达真正的终结 finalization 边界 时仍处于 pending/delivered 的每一条 steering 行，而这背后的成因不止一种：某次 /steer 调用确实可能恰好在 worker 关闭新准入之前完成 durable 提交（这是真实的竞争）；但同样常见的 情况是，图从始至终就没有调用过 drain_steering() 去消费一条其实一直可见的行——这是普通的 应用层未消费，根本不是竞争。Runtime 目前无法从现有数据中区分这两种情况，因此它也不假装能 区分：两者都得到相同的 unconsumed_at_final_boundary 原因。与其仅因为存在一条 steering 事件就强制该 run 进入无限重试循环——这会惩罚那些本就合法地从不调用 drain_steering() 的 图——Runtime 会把这条行 durably 转为 superseded，并以之前已经算出的结果正常终结该 run。 这种情况下 run.steer.superseded 事件绝不会被静默丢弃：它总是与 run 的终结状态在同一个 durable 事务中一起提交，并且在重试下是幂等的（对已经 superseded 的行重复尝试转换不会 产生重复事件）。

字段说明：

• steering_event_id：被消费的 steering 事件在当前 run 下的 id（如果该事件是从旧 run 迁移过来的，这是迁移后的新 id，不是客户端最初收到的 id）；
• source_event_id：客户端最初 /steer 调用收到的根 id。同一根 steering 即使经过多次 pause/resume 迁移，该字段在每一跳都保持一致，客户端可用它把最终 run.steer.consumed/run.steer.superseded 与自己最初发出的请求关联起来。这一行为按具体 生命周期事件而定，并非统一规则：在 run.steer.accepted 与 run.steer.consumed 上，仅当 事件来自迁移时才出现该字段——直接提交（从未被迁移）的事件在这两类事件上没有此字段； run.steer.superseded 则不同：它总是把 source_event_id 设为 event.source_event_id or event.id，因此即便是一条直接提交、从未迁移过的事件，其 superseded 记录里也会带有一个根 id——就是它自己的 id；
• sequence：该 steering 事件在其所属 run 的 steering 序列里的序号（与 run 事件流的 sequence 是两个独立计数器）；
• kind：透传自 /steer 请求体的 kind；
• queue_latency_seconds：从该 steering 最初 durably accepted（包括跨 resume 累积的 等待时间）到被消费的秒数；
• node：消费该事件的节点名；
• namespace：该节点所在的 subgraph 命名空间路径（数组）；
• task_id：区分同一 superstep 内并行/Send 任务的具体 task。

durable source 是 PostgreSQL，Redis 只是可选加速器。 run.steer.accepted、 run.steer.consumed 和 run.steer.superseded 都是先 durably 写入 PostgreSQL 再对外可见的；Redis pub/sub 只用于 提示 worker "可能有新 steering 了"，从而降低轮询延迟。即使 Redis 通知丢失（连接断开、 Redis 重启等），worker 仍会在下一个安全点检查/轮询 PostgreSQL 并最终消费——不会因为 Redis 通知丢失而永久遗漏一条 steering。同理，commit_steering_consumptions_if_owned() 是幂等的： worker 因瞬时故障重试同一批 consumption 时，只有真正发生状态转换的事件才会产生新的 run.steer.consumed，不会为已经消费过的事件重复生成。

重试策略

1. 只对 retryable=true、网络故障、429 和临时 5xx 使用有界指数退避；
2. 遵守 Retry-After；
3. 创建 run 重试复用相同 Idempotency-Key 与完全相同请求；
4. SSE 重连复用最后 sequence，不创建新 run；
5. 不自动 redrive 确定性 schema/tool 权限错误。