feat(chv): 架构与代码质量 9.5+ 提升——长函数清零、WarmPool facade、#215 对齐、审计计数、只读 VM 字段、ADR-8~11

docs/chv-architecture.md

@@ -72,9 +72,67 @@
 
 - 现状：#215（timeouts/gates/quota/sandbox_policy）未合并，
   本链 base 里无其模块，本轨不复制其代码。
-- 接口对齐点（#215 合并后机械替换，非重写）：超时类
-  api/ready/task 解析 → timeouts；门禁类 preflight/容量/
-  磁盘配额/egress fail-closed → gates；配额类 max_vms/disk_gb
-  （任务成本仍走 worker quota）→ quota；隔离类单任务单 VM/
-  磁盘 copy/egress 代理/SSH 钉死/池一次性与孤儿清理 →
-  sandbox_policy。替换时须重跑本链 163 项测试，不得改语义。
+- 纠正（feat-chv-arch95plus，核对过 #215 远程分支真实
+  函数后）：上一轨 ADR-7 的“超时→timeouts、配额→quota”
+  泛化映射是错的。#215 的 timeouts 收敛的是审批/队列
+  超时（None/0=不过期），quota 是按月美元配额，与 CHV
+  的 api/ready 秒数（0 无效）和 VM 数/磁盘 GB/快照数
+  单位与语义都不同，硬套会改行为，故这两项无映射。
+- 真实映射（已落代码，见 cloud/chv/compat215.py）：
+  gates.resolve_inside(base, rel) 目录门 → CHV 快照/磁盘
+  路径白名单已在 hardening 里使用，合并后改为 import；
+  sandbox_policy.tmpfs_isolated → CHV 客机 /tmp 落客机
+  磁盘、一律不隔离（fail-closed），合并后改为 import。
+  其余 #215 函数（审批、控制门、合并状态门、worker 寻址）
+  与 CHV 无交集，不映射。替换时须重跑本链测试，不得改语义。
+
+## ADR-8 WarmPool 生产隔离：facade 而非类导入
+
+- 决策：生产路径（worker 启动/关闭）只调
+  cloud/chv/pool.py 的 reconcile_orphans_for_executor()
+  facade，该函数内部才构造 WarmPool 并只调
+  reconcile_orphans()；生产 dispatch 绝不调 prewarm/
+  acquire/release，executor.py 也不 import pool。
+  WarmPool 类与 sandbox re-export 保留仅为兼容（旧测试
+  import 路径），新代码不得经类入口进实验接口。
+- 测试钉住：facade 测试断言 acquire/prewarm 绝不被调；
+  executor 不 import pool 由模块依赖检查覆盖。
+
+## ADR-9 审计失败取舍：记日志 + 计数，不中断任务
+
+- 选项 A（失败即中断任务）：审计完整性最强，但 DB 短暂
+  不可用会把一次审计失败放大成任务失败，且与 worker
+  全局 best-effort 语义冲突，CHV 单独硬中断是不一致的。
+- 选项 B（失败记日志 + 计数 + 不中断任务）：已选。
+  executor._emit 失败时记宿主 error 日志并累加
+  audit_failure_count（宿主可观测，非任务状态），任务
+  继续；审计完整性本身没有保证，文档与就绪清单明写。
+- 边界：本决策只针对 VM 生命周期审计；VM 启动/关机等
+  门禁失败仍按原有分类失败处理，不受本条影响。
+
+## ADR-10 长函数抽不动的耦合点（本轨后已无 >50 行函数）
+
+- 本轨后 cloud/chv/ 全部函数均 ≤50 行，上一轨的 7 个
+  长函数全部拆完：stop_vm（进程清理/文件清理/脏标记三
+  helper）、wait_guest_ready（provisioned 守卫/不匹配检查）、
+  restore_vm（校验/启动段）、cleanup_stale_secrets（单 VM
+  清理/活 VM 判定）、cleanup_stale_vms（死 socket 扫描/
+  登记清理）、_unix_socket_api（读头/解析长度/读体/解析
+  响应）、validate_net_entries（归一化/去重/冲突检查）、
+  build_chv_config（组装段纯移动）。
+- 残留耦合点（已拆但仍需注意）：stop_vm 的三块清理共享
+  同一脏标记，任一块失败即整 VM 标记脏（有意，不拆成
+  三个标记）；_unix_socket_api 的读满语义仍由四个 helper
+  共同保证，改任一 helper 须重跑截断/超时测试。
+
+## ADR-11 只读 VM 字段边界：chv_vm_dead 不是 live 状态
+
+- 决策：server 任务序列化只在 CHV 任务且 worker 已把
+  VM 死亡写进 interrupted_reason 列时返回 chv_vm_dead=True，
+  其它情形字段不存在；worker 终局时把执行器的 vm_dead
+  原因写回该列（见 worker.py 终局块），否则该字段在
+  生产里永远不出现。
+- 边界：该字段是“已报告死亡”，不是“VM 活着/死了”的
+  live 状态——server 进程没有 VM 登记表，live 状态编不
+  出来；前端无该字段时不显示 VM 状态，不猜测。VM 控制
+  按钮仍不做（后端无控制端点且安全审计 No-Go）。

docs/chv-production-readiness.md

@@ -426,3 +426,36 @@
 - 真机动态渗透、压测（无 KVM，做不了，只列清单）；
 - WarmPool dispatch 前查池接线（已定案不做，见 ADR-5；重启须先
   实现任务盘重供给并补不变量测试）。
+
+## 12. 架构 9.5+ 提升轨 feat-chv-arch95plus（堆叠于 #252 之上）
+
+> 验证方式标注（本轨新增，逐条不混淆）：静态 = 代码 + mock
+> 测试已覆盖；真机 = 须 KVM 宿主验证；压测 = 须并发负载验证。
+> 凡写“代码已做”而未标真机/压测的，一律只代表静态通过。
+
+- 长函数：cloud/chv/ 全部函数 ≤50 行（静态，mock 测试覆盖
+  提取后的 stop/wait/restore/清理/接收/校验/组装段）。
+- WarmPool 生产隔离：生产路径只调 reconcile facade（静态）；
+  预热收益仍是实验性，真机收益未验证（真机）。
+- #215 对齐：目录门与 tmpfs 口径已落代码（静态）；超时与
+  美元配额无映射，#215 合并后替换为 import 仍须重跑测试
+  （合并后，静态）。
+- 审计失败：记日志 + 计数 + 不中断（静态）；审计完整性在
+  DB 故障下的实际表现仍须真机/故障注入验证（真机）。
+- 供应链：BUILDINFO 事后 lockfile 校验脚本已落（静态）；
+  事前 apt/pip 精确 lockfile 仍缺（须构建宿主，外部）。
+- 只读 VM 字段：chv_vm_dead 派生自 worker 已写回的
+  interrupted_reason（静态，mock 测试覆盖）；live VM 状态
+  仍无字段，VM 控制按钮仍不做（后端无控制端点 + 安全 No-Go）。
+- 合并前 diff 复核清单（合并时逐项打勾，不在本轨内做）：
+  server 白名单、worker 断点分支、sandbox re-export、
+  console.html 构建产物与 src 一致、#215 合并后的 import
+  替换点。
+- 真机验证清单（沿用 §11.5，另加本轨项）：VM 死亡横幅在
+  真任务中断后是否出现、审计失败计数在 DB 故障时是否
+  累加且任务不中断、快照白名单目录门在符号链接逃逸时
+  是否拒绝。
+- 灰度启用清单（启用时逐项打勾）：CI 变绿 → 按 #216→#252→
+  本 PR 顺序合并 → KVM 宿主 + 防火墙清单 → 镜像构建发布
+  → §11.5 + 本节真机清单全过 → 默认关闭下单租户/受信项目
+  灰度 → 全量多租户（须另行决策，不在本轨内默认开启）。