qinglong/docs/adr/ADR-0412-durable-copilot-pre-model-terminalization-and-unknown-resolution.md

ADR-0412：耐久 Copilot Pre-Model 终态化与 Model Unknown Resolution

• 状态：Accepted
• 日期：2026-08-15
• 关联 RFC：QL-RFC-0001 D-320、Phase 2
• 关联 ADR：ADR-0087、ADR-0407、ADR-0408、ADR-0409、ADR-0411

问题

ADR-0411 已把 Cluster Copilot failure diagnosis 组合到既有、默认关闭的 Cluster AI 进程，但成功链之外仍有两类不收敛窗口：

1. Tool failed|timed_out、日志 not_found|pending|missing|retired、执行 Tool 所需的固定预算不足、数据库观察到 deadline 或 cancellation 时，Model 尚未开始，diagnosis Run 可能永久停留在 running；
2. Provider 已开始但结果不可确认时，通用 ModelInvocation 会耐久记录 outcome_unknown 和 lost Step。人工 fail|cancel resolution 会产生一个新的 resolved Step digest，原 Copilot finalizer 却仍只接受 unknown completion 时的 lost digest，因此正确 resolution 也无法终态化父 Run。

不能由调用者直接提交 outcome/reason，也不能用进程内异常或定时器伪造耐久终态。路由器和低配设备部署还要求该补强不能增加 package、进程、连接、队列、watcher、timer 或默认 Profile 闭包。

决策

1. 在 @qinglong/ai 的既有 copilot/failure-diagnosis/terminalization 领域目录建立一个 pre-Model terminalization capability，并仅通过 failure-diagnosis-pre-model-terminalization 精确 subpath 发布。它不是新 package，也不从 package src 根平铺实现文件。
2. terminalizer 只接受三种受信触发：耐久 Tool failure completion、耐久 Tool success 加受审日志 projection、或无调用者事实的 boundary observation。repository 再从数据库读取 exact admission、Run、Tool/Model Step、Model start existence 和数据库时间；调用者不能指定 reason、outcome、Step mutation、Run version 或时间。
3. reason 与结果采用封闭映射：
   • tool_failed → Run failed，取消尚未运行的 Model Step；
   • tool_timed_out → Run timed_out，取消 Model Step；
   • log_not_found|log_pending|log_missing|log_retired → Run/Model Step failed；
   • tool_budget_exhausted|deadline_exceeded → Run timed_out，按 Step 当前状态写 timed_out|cancelled；
   • cancellation_requested → Run cancelled，取消未开始的两个 Step。
4. 任何 Model start 已存在时都拒绝 pre-Model terminalization。Model 已经跨过外部副作用边界后，只能使用 Model completion/recovery/resolution 语义，不能把“不知道”改写为“没有执行”。
5. pg-9021-ai-copilot-failure-diagnosis-pre-model-terminalizations 增加一个 append-only content-free receipt ledger。ql3_runtime 只有 SELECT, INSERT，PUBLIC 和其他角色没有权限。一个 SERIALIZABLE 事务锁定 Run/Step，复验 admission、reason evidence、version/digest 和 Model-start absence，原子提交 StepRun mutations、RunEvents、父 Run 终态和 receipt；COMMIT response loss 通过 receipt exact replay 收敛，不重复 Tool、日志读取或 Model 调用。
6. application service 在 Tool 执行前先检查 boundary terminalization；Tool failure 和非 available 日志 projection 直接进入 terminalizer；只有 available projection 才继续 unlock/Model。Tool 的固定五秒预算必须完整落在 plan deadline 内，否则在 start barrier 前终态化。并发调用继续由既有 request coalescing 收敛。
7. outcome_unknown 不自动重试、不自动假定失败。强认证 User 仍须通过通用 DurableModelInvocationResolutionCoordinator 显式选择 fail|cancel|retry。Copilot finalizer 对普通 completion 校验 completion 后 Step digest；对 unknown 的 fail|cancel 校验 resolution completion binding 和 resolution mutation 的 resolved Step digest，再终态化父 Run。retry 保持 in-progress，且确定性 invocation identity 不允许偷偷再调用 Provider。
8. 该 capability 继续 caller-driven，并复用既有 PostgreSQL AI Pool、Run/Step ledger、Tool completion、ModelInvocation resolution 与 Cluster composition；不新增 daemon、scan、timer、watcher、队列、cache、HTTP/CLI/UI/MCP route、Pod 或 Kubernetes API 权限。默认 Edge/Standalone 及其 AI 制品不导入 Cluster-only composition，低配部署没有新增常驻工作。

被否决方案

1. 由 application catch 后直接返回失败：没有耐久 Run/Step/Event 事实，崩溃和 replay 会漂移。
2. 调用者提交 reason/outcome：会把数据库时间、取消事实和 Tool completion authority 暴露给不可信边界。
3. 后台轮询扫描所有 diagnosis Run：增加每副本 timer/数据库负载，并与 caller-driven 组合重复竞争。
4. Model start 后仍走 pre-Model terminalizer：可能把已经产生费用或外部结果的调用伪装为未执行。
5. 将 unknown completion 直接映射为 failed：抹掉真实歧义并绕过显式人工 resolution。
6. 新增 terminalization package：没有独立部署、依赖、权限或多 consumer 边界，只会制造薄 package。

验证标准

1. 单元测试覆盖 Tool failure/timed-out、四种日志状态、deadline、Tool budget、cancellation、exact replay、并发 coalescing、过早触发和 Model-start 后拒绝。
2. PostgreSQL migration 测试固定 migration ID、顺序、表约束和 SELECT, INSERT 最小权限；package/dependency/import/deployment 审计必须保持零 finding。
3. PostgreSQL 18 physical HA 以三个独立 diagnosis Run 证明：成功基线、日志不可用 pre-Model terminalization、unknown completion→人工 fail resolution→finalization；晋升后全部 exact replay，不重复日志读取、Tool 或 Model 外部执行。
4. 18-package clean build/test、完整 backend、14 档 Local artifact、GitNexus staged/change detection 全通过后才允许阶段性提交。

当前验证

1. @qinglong/ai 完整测试 244 pass/3 条件 skip/0 fail；新增 9 条 pre-Model 场景覆盖 Tool failure、四种日志状态、deadline、固定 Tool budget、cancellation 和 Model-start fence。
2. 18 个 QL3 package 从清空全部 dist 开始完成拓扑构建和全包测试，非沙箱 TLS loopback 回归全绿；backend 1,207 pass/2 条件 skip/0 fail。
3. workspace 保持 18 个 package，singleSourcePackages=[]、shallowSourcePackages=[]。AI 192 个源码中 191 个位于嵌套领域目录；新增五个源码全部位于既有 failure-diagnosis 领域目录，package 根仍只有一个 16 行 public entrypoint。local-command-file 虽小但保留多 consumer 的独立 POSIX 文件安全边界，两个 migration 密集目录继续作为有顺序上限的 ledger 接受审计。
4. Edge import、Cluster dependency、package boundary 与 Cluster deployment 审计兼容且零 finding；14 档 Local artifact 通过，说明 Cluster-only terminalizer 未进入默认路由设备闭包。
5. PostgreSQL 18.6 arm64 physical HA 137/137、timeline 1→2；21 条 AI migration、新 append-only ledger、最小权限、两条新增恢复链和晋升后 exact replay 全部通过。私有报告 SHA-256 为 6eaeb20615a62d153c5a69687344f41f31351c6ecf111cfb9cbafad115538c83，独立离线审计 compatible=true、零 finding。

后续门禁

下一 Gate 才能增加认证、Policy、audit、request identity 与 source fence 保护的 Cluster 产品 API；CLI/UI/MCP 必须复用同一 capability，不得建立旁路执行器。产品入口还需补多副本并发、真实外部 Provider、费用/取消可观测性和明文负证据后再评估默认策略。