Run Governance API

所有端点使用 Gateway 监听地址和 Authorization: Bearer gw_...。POST 请求要求 Content-Type: application/json、不超过 16 KiB 的正文和 Idempotency-Key。

Scope 与端点

Scope 与端点
Scope	方法与路径
`work_unit:create`	`POST /halro/v1/work-units`、`POST /halro/v1/work-units/{id}/close`
`run:create`	`POST /halro/v1/runs`、`POST /halro/v1/runs/{id}/close`
`run:attach`	在模型调用上接受 `X-Halro-Run-ID`；还需要 `inference`
`governance:read`	`GET /halro/v1/work-units/{id}`、`GET /halro/v1/runs/{id}`
`outcome:write`	`POST /halro/v1/work-units/{id}/outcomes`

所有资源都受 Gateway Key 所属 Project 限制；跨 Project 查询与附加不会泄露资源存在性。

创建 Work Unit

POST /halro/v1/work-units

{"outcome_definition_ids":["odef_xxx"]}

outcome_definition_ids 可省略，最多 8 个，必须属于同一 Project 且当前 enabled。创建时冻结 Definition ID/version。首次成功返回 201；同一 Idempotency-Key 和相同请求体重放返回 200 与同一资源。

读取与关闭 Work Unit

GET  /halro/v1/work-units/{id}
POST /halro/v1/work-units/{id}/close

GET 返回 work_unit、其 runs 和 outcomes。关闭正文必须是 {}。关闭后不能再创建 Run；重复关闭是幂等重放。

创建 Run

POST /halro/v1/runs

{
  "work_unit_id": "wku_xxx",
  "budget_micros_usd": 500000,
  "ttl_seconds": 3600
}

预算和 TTL 省略或为 0 时采用 Project 默认值；显式值不得超过 Project 上限。单个 Work Unit 最多 32 个 Run。响应中的 budget_state 是 available、fully_reserved 或 depleted， remaining_micros_usd 已扣除 committed、reserved 与进程内 pending。

读取与关闭 Run

GET  /halro/v1/runs/{id}
POST /halro/v1/runs/{id}/close

关闭请求可传 {"reason":"completed"}；省略时默认 completed，长度必须是 1–64 字符。过期状态由读取时钟派生。关闭或过期的 Run 拒绝新的附加调用。

报告 Outcome

POST /halro/v1/work-units/{id}/outcomes

报告 Outcome
字段	必填	约束
`definition_id`	是	必须是 Work Unit 创建时冻结的 Definition
`value`	是	必须位于 BOOLEAN/CATEGORICAL 允许值内
`observed_at`	是	RFC 3339 业务观察时间
`evidence_ref`	否	最长 128 字符的不透明引用；拒绝 URL、控制字符和凭据形状
`evidence_sha256`	否	64 位小写十六进制 SHA-256
`supersedes_outcome_id`	修订时	必须指向该 Work Unit/Definition 当前 Outcome

首次上报返回 201；幂等重放返回 200。修订生成新 out_...，旧记录保留。每个头最多 20 个 revision，Work Unit 关闭后的写入窗口是 30 天。

主要错误

主要错误
状态	code	调用方处理
400	`invalid_request` / `invalid_outcome`	修正字段、值域或 Content-Type，不重试原请求
400	`invalid_idempotency_key`	为逻辑操作提供合法且稳定的 Key
403	`gateway_key_scope_denied`	更换已获授权的 Key，不做盲重试
403	`run_budget_exceeded`	停止该 Run，或由管理员调整策略后创建新的合规 Run
404	`work_unit_not_found` / `run_not_found`	核对 Project 和资源 ID
409	`idempotency_conflict`	同一 Key 被用于不同请求；生成新逻辑操作前先调查
409	`run_not_active` / `work_unit_closed`	不再向终态资源写入或附加请求
409	`outcome_revision_conflict`	读取当前 Outcome，使用其 ID 重新提交修订
409	`outcome_write_closed`	已超过修订数或关闭后写入窗口
429	`governance_rate_limited` / `governance_resource_limit`	尊重 `Retry-After` 或降低资源创建速率
503	`run_governance_unavailable` / `governance_unavailable`	状态权威不可验证；不要把失败当作空数据或成功

完整业务流程见接入运行治理。