qinglong/docs/adr/ADR-0168-durable-model-invocation-step-run-fence.md

# ADR-0168：Durable ModelInvocation 与唯一 StepRun Fence

- 状态：Accepted
- 日期：2026-07-26
- 关联：RFC D-12、D-13、D-156、D-157；ADR-0156、ADR-0167、ADR-0170

## 背景

Model Gateway 已经能执行受预算约束的远程调用，但进程内 audit 不能回答崩溃、
COMMIT 响应丢失、集群 promotion 或用户取消后的 durable outcome。另建一套
Invocation `pending/running/succeeded` 状态会与既有 Run/StepRun 产生双写；自动重试
结果未知的远程模型调用又可能重复计费，并产生不同输出。

同时，禁用 AI 的路由设备不应因为 workspace 中存在 AI 包就创建 AI 表、加载 adapter
或增加默认 Profile 产物。持久化能力需要复用现有 SQLite/PostgreSQL 部署边界，但
不能再拆一个只有 repository 的 package。

## 决策

### 1. ModelInvocation 是 model StepRun 的 receipt，不是第二状态机

每次 invocation 必须绑定一个 `StepRun.kind=model`：

- admission 原子提交 `ready → running`、Run version/event、RunEvent、
  StepRunMutation 和 ModelInvocationStart；
- completion 原子提交 usage/cost/byte receipt 与
  `running → succeeded|failed|timed_out|lost`；
- `succeeded` 的 StepRun 只保存 `outputRef=model-invocation:<id>`，正文默认不进入
  Start、Completion、RunEvent 或 mutation；
- deadline 映射为 `timed_out`；
- provider 调用后的 caller abort、consumer stream cancel 或其它结果未知映射为
  `lost/outcome_unknown`，只允许人工裁决，不自动 replay。

Start/Completion/Command 使用独立 v1 schema 和 domain-separated SHA-256 digest，
单 record/command JSON 最大 24 KiB。完整绑定 Project、Run、StepRun、Trace、provider、
model、policy revision、request digest、deadline、输入/输出字节、token 与可选费用。

### 2. mutation identity 必须由摘要派生

requestId 最长 128 字符，不能用 `requestId + ':started'` 生成事件 ID。
`createModelInvocationMutationIdentity` 以 invocationId、phase 和独立 domain 派生完整
SHA-256，并产生均不超过 128 字符的 mutation/event/dedupe identity。Start 与
Completion normalizer 同时复验 identity、StepRun digest/version、Run event sequence
和 command digest；身份或内容复用漂移一律 conflict。

### 3. durable admission 不得被 Abort race 脱离

Policy 解析和 provider Promise 可以被 deadline 从调用方视角中止；durable admission
不可以。Gateway 必须等待 audit/start sink 自身的受限数据库操作结束：

- admission 未成功时 provider I/O 为零；
- deadline 在 admission 中到达且 start 最终提交时，随后写入 `timed_out` completion；
- admission sink 失败时返回 `MODEL_AUDIT_UNAVAILABLE`；
- terminal sink 失败时不把 provider 结果交给上层。

这会让一个超时的 admission 在 repository timeout 内继续占用一个有界并发槽，但避免
后台出现无法解释的 running StepRun。repository 必须有 statement/busy timeout，不能
用 Gateway Promise race 替代数据库取消和事务收敛。

### 4. migration、repository 与 coordinator 留在可选 AI 能力族

SQLite 和 PostgreSQL feature migration、原子 repository、durable coordinator 与
recovery 都进入既有 `@qinglong/ai` 的显式 subpath，不新增 workspace package。
双方言实现只依赖 `node:sqlite` 或 runtime-core 的 structural PostgreSQL
Pool/Client port，不导入 Drizzle、`pg`、local-sqlite 或 cluster-postgres，也不增加
optional peer。具体 Profile 只在启用 AI 时注入已有数据库 authority。

AI schema 使用独立 feature migration stream：

- AI 未启用时不运行 feature migration、不创建表；
- feature history 使用独立表、stream identity 和 checksum，绝不向双方言 main
  migration history 插入 feature row；
- PostgreSQL feature tables/history 位于独立 `ql3_ai` schema，避免被核心 `ql3`
  exact readiness 误判为未知表；SQLite readiness 保留精确 owned-table 校验并允许
  同库显式 feature table；
- 启用 composition 必须先显式 migrate/readiness，再构造 repository；
- PostgreSQL runtime role 对不可变 invocation 表只取得 `SELECT/INSERT`，不得为了
  `FOR UPDATE` 扩大 `UPDATE/DELETE`；
- repository subpath 只取得数据库 authority，不取得 provider credential 或外部网络。

Gateway admission sink 返回 `created|existing`。只有 `created` 可开始 provider I/O；
`existing` 包括正常重放和 COMMIT 响应丢失后的耐久回查，必须返回
`MODEL_INVOCATION_REPLAY_BLOCKED`，禁止再次调用 provider。bounded recovery 只扫描
已过数据库 deadline 且没有 completion 的 start，并收敛为
`lost/outcome_unknown`，不自动重放模型。

### 5. unknown outcome 只能以不可变人工 Resolution 推进

`lost/outcome_unknown` 不再是永久死点，也不能被自动 retry。唯一出口是受信 User
提交一个 `qinglong/model-invocation-resolution@v1` receipt，决策严格限定为：

- `retry`：原子执行 `lost → ready`，清除旧结果字段；后续 `ready → running` 必须
  使用新的 invocationId，StepRun attemptCount 在新 start 时增加；
- `fail`：原子执行 `lost → failed`，固定
  `resultCode=model_outcome_rejected`；
- `cancel`：原子执行 `lost → cancelled`，固定
  `resultCode=model_outcome_cancelled`。

Resolution/Command 绑定原 Completion digest、Project/Run/StepRun/Trace、User ID、
StepRun version/digest、mutation/event/dedupe identity 与时间。repository 必须在同一
SQLite/PostgreSQL 事务内复验原 completion 仍是 `outcome_unknown`、当前 StepRun 仍
精确等于该 completion 的 `lost` winner，然后提交 StepRun/Run/RunEvent/
StepRunMutation/Resolution。每个 invocation 只能有一个 Resolution；相同命令 exact
replay，不同 User/decision conflict。

一个 StepRun 可以有多个 attempt，因此 Start/Completion 表不能再对
`(run_id, step_run_id)` 建唯一索引。它们改用包含时间和 invocationId 的普通历史索引，
invocation、mutation、RunEvent 和 digest 继续保持唯一。旧 Start/Completion/
Resolution 永不覆盖，新 attempt 形成新的 invocation 链。

## 被否决方案

1. 把 adapter 放入双方言 storage package 并反向 optional peer AI：会污染默认 packlist，
   且真实 Edge artifact 已证明即使 AI 不安装也会增加文件。
2. 在 AI 包引入 `pg`/Drizzle：会扩大可选 Edge AI 的依赖和供应链闭包。
3. 把 durable contract 放入 runtime-core root：禁用 AI 的基础 artifact 也会增长。
4. 把 AI 表加入双方言 main migration：禁用功能仍产生 schema、备份和写放大。
5. start audit 使用 `Promise.race`：调用返回后事务仍可能提交 running 状态。
6. 对 unknown outcome 自动 retry：可能重复计费且输出非确定。
7. 保存 Prompt/输出便于调试：默认扩大 Secret、个人数据和备份泄露面。

## 当前验证

- `@qinglong/ai` 默认门：50 pass、1 条 PostgreSQL 条件 skip；真库门另 1 pass；
- 最大长度 requestId 的 mutation/event/dedupe identity 均不超过 128 字符；
- admission deadline 期间 provider 调用为零，start sink 不脱离，随后写入明确的
  deadline failure；
- success、deadline 与 caller-abort 分别收敛为
  `succeeded`、`timed_out`、`lost/outcome_unknown`；
- SQLite 与 PostgreSQL feature history 使用独立表；主迁移与 AI 迁移交错重启通过；
- SQLite 原子 admission/completion、provider replay block 和 expired recovery 通过；
- SQLite Edge `DELETE/FULL` 与 Standalone `WAL/FULL` 共 14 个真实文件
  `SIGKILL` 窗口通过：10 个 COMMIT 前窗口零部分事实并重放 `created`，4 个 COMMIT
  后窗口重启为 durable winner 并重放 `existing`，全部 `integrity_check=ok`；
- PostgreSQL 18 真库以 migration/runtime 分角色验证原子事务、exact replay、rollback、
  bounded recovery source，以及 invocation 表仅 `SELECT/INSERT`；
- PostgreSQL ModelInvocation `COMMIT` 已提交但响应丢失时，provider 调用为 0，
  coordinator durable recheck 返回 existing，recovery 收敛为
  `lost/outcome_unknown`；
- SQLite 与 PostgreSQL 都覆盖 User `retry/fail/cancel` 原子 Resolution；`retry`
  后同一 StepRun 可用新 invocationId 进入第二次 running，attemptCount 从 1 增至 2，
  原 unknown completion 保持不变；不同 decision replay 被拒绝；
- dependency audit `findings=[]`，AI 只有 runtime-core workspace dependency；
- Edge 基线仍为 3,902,728 bytes/478 files/40 modules；edge-ai 为
  4,212,508 bytes/508 files/41 modules，standalone-ai 为
  4,212,580 bytes/508 files/41 modules；
- ADR-0170 已把非空 usage 从 Completion 原子投影为独立不可变 ledger；失败 outcome
  也保留已知 usage，无 usage 不伪造零成本，exact replay 同时复验 Completion 与
  ledger；
- PostgreSQL 18.4 arm64 完整 HA 门通过 physical streaming、timeline 1→2、fencing、
  双 control replica、`pg_rewind` 与总 `passed=true`；`ql3_ai` 独立 history 和
  Start/Completion/Resolution/UsageLedger 四表在 promotion 前后 9001/9002
  checksum、表集与 runtime append-only ACL 完全一致，
  `optionalAiFeatureSchemaSurvivesPromotion=true`。

## 后续门禁

1. credential binding audit 的双方言持久化，以及 binding digest 与 invocation
   查询的关联；Project-bound SecretRef 和可清零 material lease 已由 ADR-0169
   完成；
2. ADR-0170 ledger 之上的原子 Project quota、计价 catalog/revision、不可变 rollup
   与 retention coverage receipt；
3. AI invocation 数据行级 promotion/partition fault，而不只 schema promotion；
4. 正式产品 importer、配置 ceremony、read-only usage/Copilot/MCP authority；
5. 在这些门禁完成前保持 HTTP/MCP/UI 产品 route 和费用配额关闭。