feat(ql3): terminalize copilot diagnosis failures

docs/QINGLONG_3_0_ARCHITECTURE_RFC.md

@@ -11,6 +11,7 @@
 
 最新增量证据（2026-08-15）：
 
+- D-320/ADR-0412（已接受）：Cluster Copilot failure diagnosis 已补齐产品入口前的非成功收敛边界。新增的 pre-Model terminalizer 只从 durable Tool failure、受审日志 projection 或数据库观察到的 deadline/cancellation 派生封闭 reason，在 Model start 不存在时以一个 SERIALIZABLE 事务原子提交 StepRun mutations、RunEvents、父 Run 终态和 `pg-9021` append-only content-free receipt；Tool `failed|timed_out`、日志 `not_found|pending|missing|retired`、五秒 Tool budget 不足、deadline 和 cancellation 均可 exact replay。Model 已开始后的 `outcome_unknown` 继续要求强 User 显式 `fail|cancel|retry` resolution；Copilot finalizer 现在对 `fail|cancel` 精确校验 resolution mutation 的 resolved Step digest，既不伪造失败也不自动重试 Provider。实现复用既有 AI package、Cluster AI 进程、Pool 与 ledger，不增加 package、进程、连接、timer、watcher、队列、cache 或产品 route；workspace 仍为 18 package、无单文件/浅平 package，AI 192 个源码中 191 个位于嵌套领域目录。AI 完整测试 244 pass/3 条件 skip，18-package clean build/test 与 backend 1,207 pass/2 条件 skip/0 fail，四项架构审计和 14 档 Local artifact 全部通过。PostgreSQL 18.6 arm64 HA 137/137、timeline `1→2`，覆盖日志不可用 pre-Model terminalization、unknown completion→人工 fail resolution→Run finalization 及晋升后零外部副作用 exact replay；报告 SHA-256 为 `6eaeb20615a62d153c5a69687344f41f31351c6ecf111cfb9cbafad115538c83`，离线审计零 finding。下一 Gate 才增加认证、Policy、audit 与 source fence 保护的 Cluster API，并由 CLI/UI/MCP 复用，仍不得建立旁路执行器。
 - D-319/ADR-0411（已接受）：Cluster Copilot failure diagnosis 已在既有 `ql3-cluster-control-ai` 进程内完成默认关闭的 production composition。Prompt 与 Copilot 共享同一个 PostgreSQL AI Pool、Model Gateway、Provider client、恢复扫描、quota/pricing ledger 与 `maxConcurrent` 预算；有界 successful-completion router 只向声明 exact invocation 的 durable sink 分发，不复制 Gateway、连接或隐藏队列。application service 只接受 source Run/request identity，从数据库当前 Run、latest Attempt、Project Tool snapshot、Policy 和 canonical read-only egress config 派生计划，先 admission，再以 durable plan、historical key 与确定性 nonce 修复 admission→Artifact crash window，随后复用 Trusted Tool、Worker Artifact range reader、Model Gateway 及独立的 invocation/result/model-output 三域 keyring。能力保持 caller-driven，不增加 timer、watcher、队列、HTTP/CLI/UI/MCP route 或 Kubernetes API 权限；Kubernetes 独立可选 component 仅投影 config 与三个 0440 keyring。最终 AI 238 pass/3 条件 skip、Cluster Control 240 pass/2 条件 skip、18-package clean build/test 与 backend 1,207 pass/2 条件 skip/0 fail，四项架构审计、14 档 Local artifact 全部通过；workspace 仍为 18 package、无单文件/浅平 package，AI 187 个源码中 186 个、Cluster Control 59 个中 57 个位于嵌套领域目录。默认 Edge/Standalone 保持 2,589,890/2,589,968 bytes，Edge/Standalone AI 为 3,064,454/3,064,544 bytes，证明 Cluster-only composition 未进入小设备闭包。PostgreSQL 18.6 arm64 HA 130/130、timeline `1→2`，报告 SHA-256 为 `981299b454dce5541e9596450b85816dc40559cba8dc42adf3d5fea571c3d3a6`；本 Gate 不改 migration/schema/role/SQL/HA 拓扑。下一 Gate 是 Tool failure、日志 missing/retired/pending、deadline/cancel 与 Model outcome-unknown 的 durable terminalization/recovery，完成前不开放产品入口。
 - D-318/ADR-0410（已接受）：Cluster Copilot diagnosis Model output 获得独立的只读 projected key authority。canonical `qinglong/copilot-failure-diagnosis-output-projected-keyring@v1` manifest 只允许一个 active key 与最多 16 个 historical 32-byte key；每次 `active()`/`resolve()` 都重新执行 Cluster 私有投影文件的 direct-root、根内 atomic symlink、single-link、mode、dev/inode/size/mtime 与双 realpath fence，不使用 cache、watcher、timer 或 Kubernetes API。该 authority 以结构兼容的本地窄端口位于既有 `cluster-control/copilot/failure-diagnosis/`，只通过 `failure-diagnosis-output-keyring` subpath 发布，避免 Cluster Control 默认源码反向依赖 AI；它不复用 Prompt output、Tool invocation/result 或 Provider credential key domain，也不提前声称 Copilot 产品入口已可达。定向回归 13/13、Cluster Control 239 pass/2 条件 skip、backend 1,207 pass/2 条件 skip、18-package clean build/test、四项架构审计与 14 档 Local artifact 全部通过；workspace 仍无单文件/浅平 package，Cluster Control 58 个源码中 56 个位于嵌套领域目录。默认 Edge/Standalone 保持 2,589,890/2,589,968 bytes，Edge/Standalone AI 保持 3,061,009/3,061,099 bytes，证明 Cluster-only subpath 被裁掉。本 Gate 不改 migration/schema/role/SQL/连接/HA 拓扑，因此数据库基线继续引用 ADR-0409 的 PostgreSQL 18.6 arm64 HA 130/130、timeline `1→2`；下一 Gate 是默认关闭的完整 Cluster Copilot composition，随后补齐 Tool failure、日志 missing/retired、Model admission 前 deadline/cancel 与 outcome-unknown 的 durable terminalization/recovery。
 - D-316/ADR-0408（已接受）：Cluster Copilot 现在能够从 ADR-0407 的 durable admission 恢复 exact `qinglong.run.log.excerpt@1.0.0` authority，复用通用 Trusted Tool start barrier、加密 success/failure completion、result catalog/rekey 和内建日志 adapter；确定性 start/completion identity 让 response-loss replay 直接打开既有证据，不重复读取日志或执行 adapter。Cluster invocation Artifact 使用独立 projected keyring，提供 active+historical material，但每次读取均重新执行 canonical path/symlink/mode/inode/realpath fence，且不取得 PostgreSQL Tool result generation authority。只有 exact `succeeded` completion 才能通过 `pg-9019` 的 SERIALIZABLE 事务把 Model Step 从 `pending` 原子推进到 `ready`，同时写 RunEvent、StepRunMutation 和 append-only unlock receipt；`failed|timed_out` 不解锁。本 Gate 不执行模型、不终态化 diagnosis Run，下一 Gate 是 ADR-0405 builder + Model Gateway + Copilot encrypted model completion/terminalization。实现仍为 18 个 package，无单文件/浅平 package；AI 175 个源码中 174 个、Cluster Control 56 个中 54 个位于嵌套目录，不新增依赖、进程、连接、timer/watcher/cache 或默认 Edge 成本。18-package clean build/test 全绿，AI 229 pass/3 条件 skip、backend 1,207 pass/2 条件 skip，四项架构审计零 finding；14 档 Local artifact 全通过，默认 Edge/Standalone 为 2,589,890/2,589,968 bytes。PostgreSQL 18.4 arm64 HA 130/130、timeline `1→2`，首次执行只读两次日志、密文不含敏感 fixture，提升后 exact replay 零日志读取；报告 SHA-256 为 `d525a303696e178d777b021b376729bd2c5382fb5eb7bc98466a2b79d3940517`，独立审计与 Docker 清理通过。

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

@@ -0,0 +1,59 @@
+# 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、费用/取消可观测性和明文负证据后再评估默认策略。

docs/adr/README.md

@@ -415,6 +415,7 @@
 | [ADR-0409](./ADR-0409-cluster-copilot-failure-diagnosis-model-execution.md)                        | Cluster Copilot Failure Diagnosis Model Execution、密文输出与 Run 终态化                                                                               | Accepted |
 | [ADR-0410](./ADR-0410-cluster-copilot-failure-diagnosis-output-key-authority.md)                   | Cluster Copilot Failure Diagnosis Output Projected Key Authority                                                                                        | Accepted |
 | [ADR-0411](./ADR-0411-default-off-cluster-copilot-composition.md)                                  | 默认关闭的 Cluster Copilot Failure Diagnosis Composition                                                                                                  | Accepted |
+| [ADR-0412](./ADR-0412-durable-copilot-pre-model-terminalization-and-unknown-resolution.md)         | 耐久 Copilot Pre-Model 终态化与 Model Unknown Resolution                                                                                                    | Accepted |
 
 ## 规则