ADR-0459：按需 Project CancellationDispatch 可用性汇总

状态：Accepted
日期：2026-08-19
关联 RFC：QL-RFC-0001 D-366、PR-5、PR-7
关联 ADR：ADR-0005、ADR-0456、ADR-0457、ADR-0458
Amends：ADR-0005 的 blocked 指标出口、ADR-0458 的产品可见运维边界

上下文

ADR-0458 已提供单 Run 的低敏 inspect 和人工 rearm，但 operator 仍必须预先知道哪个 Run 被 blocked。直接依赖每个 cluster-control 副本的进程内计数会在重启、扩缩容和 failover 后丢失事实，也无法形成 Project 一致视图。新增 Prometheus server、扫描 timer 或聚合 daemon 又会制造第二个 cancellation cadence，并让低配部署为空闲可观测性持续付费。

QingLong 同时面对小型路由设备和多副本 Cluster。Local/Edge 不应引入 PostgreSQL、管理面或指标闭包；Cluster 则需要数据库事实驱动、可审计、可供 CLI/UI/告警共同消费的稳定出口。

决策

在既有 cluster-admin Run management 协议增加 run.cancellation.summary，复用原 HTTPS/mTLS process、OIDC、固定路由、请求上限、连接池和 shutdown lifecycle，不新增 package、服务、端口、timer、队列、缓存或 Kubernetes 对象。
请求只包含 Project、request/audit identity 和固定空 body schema，不接受 Run、Attempt、时间窗口、分页、状态过滤、指标标签或调用方时钟。transport 只注入强认证 User；service 使用既有 run.read，因此 viewer 可读取汇总，弱认证、agent 和 Policy fence drift 失败关闭。
Repository 在一个最长 5 秒的 SERIALIZABLE 短事务中，以 PostgreSQL transaction_timestamp() 观察 Project 当前快照，并在提交前原子写 allowed audit。它只使用 v66 已授予 Run manager 的 runs 与 run_cancellation_dispatches SELECT，不增加 migration 或数据库权限。
响应只包含固定低基数投影：五个状态计数、due 与 expired-lease 两个信号、四个 blocking-result 计数、最早 blocked 时间，以及 clear|converging|attention_required assessment 和 none|wait|inspect 建议。永不返回 Run/Attempt/Worker identity、lease owner/token/digest、PID、handle、命令、环境、Secret、日志或错误原文。
assessment 由服务端确定：存在 blocked 即 attention_required/inspect；没有 blocked 但仍有 pending/leased/retry_wait 即 converging/wait；否则为 clear/none。due 或 lease expiry 是 caller-driven 交付可接管信号，不单独把整个服务 readiness 标记为不可用。
total 必须等于五态之和，blocked 必须等于四种 blocking result 之和，due 不得超过 pending+retry_wait，expired lease 不得超过 leased，最早 blocked 时间必须与 blocked 是否存在一致且不晚于数据库观察时间。Repository 和客户端分别做 exact-shape 与交叉不变量校验。
Project ID 只用于请求作用域和响应绑定，不被设计为常驻时序指标标签。CLI、产品 UI 或告警适配器可以按需请求该固定快照；若未来导出 Prometheus，只能由部署侧选择 Project allowlist，不能让本协议隐式制造无界 label cardinality。
代码继续内聚在现有 cluster-postgres/run-management 与 cluster-admin/run-management 子域。聚合、inspect、rearm 共享同一个 management repository 与 authority，不为一个查询再拆微包，也不把文件铺到 package 的 src 根目录。

被拒绝的替代方案

每个 cluster-control 副本维护内存指标

拒绝。副本重启会清零，多副本结果无法精确合并，blocked durable state 与进程 counter 可能永久分叉。

新建扫描器或 Prometheus 服务

拒绝。扫描 cadence 会与 caller-driven Worker delivery 竞争，并增加空闲 CPU、连接、部署对象和低配运维成本。

把 blocked 直接映射到 `/readyz` 失败

拒绝。blocked 是一个 Run 的身份或协议处置事实，不代表数据库、管理面或其他 Project 不可服务。全局 readiness 失败会触发无效滚动并掩盖真正处置目标。

返回 blocked Run 列表

拒绝。列表需要分页、稳定 cursor、更多 identity 泄漏与更宽 UI 状态。本阶段先提供固定聚合；operator 从 inspect 精确诊断已知 Run，后续产品 drill-down 必须另行设计有界索引契约。

资源、安全与部署影响

Edge/Standalone 不依赖 cluster-admin、cluster-postgres 或 pg，默认与启用态均为零新增常驻开销。
Cluster 只在 operator/产品调用时使用既有单连接 Run manager pool；没有后台采集、写放大或 idle I/O。
Project 查询可利用既有 runs(project_id, created_at_ms, id) 与 dispatch run_id 索引，并受 5 秒 statement timeout、1 秒 lock timeout 和事务 idle timeout 约束；超限失败关闭，不降级为部分或伪造的健康结果。
summary 只有 allowed/denied audit 写入，不修改 Run、Attempt、dispatch 或 RunEvent，不改变 cluster-control readiness。

验证

Repository、service、transport 和客户端聚焦测试覆盖三态 assessment、计数交叉不变量、viewer run.read、强认证、原子 audit、Project 绑定、未知字段与 capability 泄漏拒绝。
cluster-postgres 为 341 pass / 0 fail / 3 conditional skip，cluster-admin 为 397 pass / 0 fail / 3 conditional skip；完整 backend 为 1,487 pass / 0 fail / 2 conditional skip，18-package clean build/test 退出 0。
package boundary、cluster dependency、Edge import 和 cluster deployment 四项审计零 finding；workspace 仍为 18 包，singleSourcePackages=[]、shallowSourcePackages=[]。
14/14 Local artifact audit 通过且字节与 D-365 相同：基础 Edge/Standalone 2,589,998 / 2,590,076，Application+AI 4,493,151 / 4,493,283。
PostgreSQL 18.6 arm64 HA 145/145：真实 ql3_run_manager 在 blocked 状态读取 Project summary，再继续 inspect、CAS rearm、production delivery、WAL replication 与 promotion；timeline 1→2，报告 SHA-256 d763157b3a781e305add3c6f0c5080820b1d65b5feefe60be6fa7006c0050107，独立证据审计零 finding。

后续

ADR-0460 已用现有 ql3 run status 完成一次性 Project 状态卡、稳定 JSON 和 0/10/20 告警退出码；ADR-0461 又以固定 16 项、快照键集和 Project partial index 完成未知 blocked Run 的有界发现。两者都不增加常驻组件或混合 Copilot Console authority。Console 可选接入、CloudNativePG live failover、多副本容量压力、固定 Linux x64/arm64 和物理 Edge 资源证据仍是独立发布门；本 ADR 不把 Docker HA 或按需汇总冒充这些现场证据。

6.6 KiB Raw Blame History Unescape Escape