qinglong/docs/adr/ADR-0279-authenticated-cluster-plugin-package-workflow-cancellation-product-entry.md

ADR-0279：受认证的 Cluster Plugin Package Workflow 取消产品入口

• 状态：Accepted
• 日期：2026-08-07
• 关联：D-29、D-35、D-47、D-87、D-213、D-257、ADR-0056、ADR-0228、ADR-0230、ADR-0271、ADR-0277、ADR-0278

上下文

Cluster Control 已有通用的 Project/Run 取消入口，也已有 Plugin Package Workflow 的 inspect/start 产品入口， 但产品用户不能通过 Package/Workflow 资源路径取消一个已经启动的 Workflow Run。若客户端先 inspect Workflow admission，再调用通用 Run 取消入口，两个请求之间存在 TOCTOU 窗口；通用入口也不能证明目标 Run 确实来自路径中的 Package 与 Workflow。

这项补齐不能复制 ADR-0228 已有的 Run cancellation 状态机、Event、远程 Worker stop 与恢复 cadence，也 不应为一个路由增加 workspace package、表、migration、Pool、listener、timer 或 watcher。PostgreSQL runtime 角色对 immutable Workflow admission 只有 SELECT, INSERT，不能为了锁定一条 append-only 证据而扩大到 UPDATE。

决策

1. Cluster Control 发布 POST /api/v3/projects/{projectId}/packages/{packageName}/workflows/{workflowId}/runs/{runId}/cancellation， operation 为 workflow.cancel，权限为 run.stop。请求复用严格的 qinglong/run-cancellation@v1 body，只接受 mutationId；reason、event identity 与时间均由服务端 决定。
2. Workflow administration capability 把路径中的 packageName、workflowId 与 runId 作为一个 workflowTarget 传给既有 ClusterRunCancellationRepository。通用 Project/Run 入口不携带该 target， 因而保持兼容。
3. PostgreSQL repository 在既有 serializable transaction 中先锁定 Project、RoleBinding 与 Run，再按唯一 run_id 普通读取 immutable plugin_package_workflow_admissions，并要求 Project、Package、Workflow 三元组逐项相等；缺失、跨 Project 或目标不匹配统一按 not-found 屏蔽。Run 锁仍使用 FOR UPDATE，admission 不使用 FOR SHARE，从而保持 runtime 角色无 UPDATE 权限的最小权限边界。
4. 目标绑定通过后继续复用同一个 repository 的 terminal、already-requested、mutation replay、Run 更新、唯一 run.cancel_requested Event 与 recovery convergence；Workflow 路由与通用 Run 路由由同一个 composition root 注入同一个 repository instance。
5. 首次接受返回 202，其余 durable outcome 返回 200。响应沿用 content-free cancellation projection； not-found 返回低敏 workflow_run_not_found，围栏错误只允许 authorization_changed、 project_mismatch、state_mismatch 三种 reason，任何未知 adapter detail 都折叠为 state_mismatch。
6. PostgreSQL HA 门必须从真实 Workflow publication/admission 出发，用明确的 workflowTarget 触发远程 Worker stop，并同时验证完成提交响应丢失、取消提交响应丢失、WAL 复制、升主与 replay 收敛。

被拒绝的方案

• 先 inspect 再调用通用 Run 路由：跨请求检查存在 TOCTOU，无法原子证明路径资源与 Run 的归属。
• 在 Workflow capability 中复制取消状态机：会产生第二套 status、mutation、Event 与恢复语义。
• 给 admission 查询加 FOR SHARE 并授予 runtime UPDATE：PostgreSQL 锁定读取要求写权限，会破坏 append-only admission 的最小权限模型。
• 相信客户端提交 plan、digest、reason 或 event ID：扩大了 capability surface，并允许调用者伪造服务端 authority。
• 新增 Workflow cancellation package 或持久表：没有独立部署、复用或生命周期价值，并违反 19-package 硬上限的收敛方向。

接受证据

• Runtime Core 437/437；Cluster PostgreSQL 定向 repository 6/6；最终 Cluster Control 175 pass/2 conditional skip/0 fail。完整 19-package 门退出 0，后端 1,101 tests、1,099 pass/2 skip/0 fail。
• Edge import、cluster dependency、package boundary schema v2、cluster deployment、worker deployment 与 local image 六项审计全部 compatible；workspace package 数保持 19，未新增 dependency、migration、表、 Pool 或常驻 cadence。
• 十档 local artifact 全 compatible，package/file/module closure 不变；Edge/Standalone 3,548,694/3,548,742 bytes，Adopted 4,147,396/4,147,480，Application 4,634,869/4,635,013，AI 4,883,616/4,883,676，Application AI 5,969,863/5,970,019；最大档距 6 MiB 仍有 321,437 bytes。
• PostgreSQL 18.4 arm64 physical-streaming HA passed=true； remoteWorkflowCancellationBindsWorkflowTarget、远程 stop requested、completion exact replay、commit response loss convergence 与 promotion survival 全部为 true。首轮真实 HA 准确捕获 FOR SHARE 的 runtime 权限失败；改为 immutable plain SELECT 后在不新增权限和 migration 的前提下通过，且 ql3-ha-* container/network/volume 零残留。
• 刷新后 GitNexus 为 42,530 nodes/96,503 edges/1,675 clusters/261 flows；复查符号全部 LOW，Workflow capability 最高 2 direct/6 impacted/0 production process，HA matrix 仅影响测试 main 流程。 detect-changes all/compare develop 分别为 12 files/31 symbols 与 14/34，均 low/0 affected process。

剩余边界

• D-213 仍需 production gateway/operator、跨区域与物理基础设施 fencing 的独立证据；Docker HA 不能替代 production STONITH。
• x64 CI/发布 runner 的同构资源门，以及固定型号路由器的断电、闪存、热环境与长时间 soak 仍未执行。
• Web UI、MCP/Agent tool surface 与外部 OIDC ceremony 仍需在同一 workflow.cancel operation 上补齐，不能 建立旁路状态机。
• 联网 production dependency vulnerability audit 因依赖元数据外发权限未获批准，本轮不重跑。